Skip to content

Tool manifest (kind: Tool)

Package: mas-runtime · Schema: tool.schema.yaml · apiVersion: mas/v1

A Tool manifest is the declarative advertise contract of one tool: name, parameters, optional protocol extras, and an impl pointer. Agents reference it via spec.tools[].ref. The Python class behind impl implements ToolContract.

Related: ToolContract · Agent · Infra ToolServerRegistry · ToolBundle

A Tool document that only declares parameters + impl is valid. Every field below title is optional. At the document level, apiVersion, kind, metadata, and spec are required; metadata.name is required. spec.impl is optional in the schema but is needed to load an executable tool. If present, impl.module_path is required.

Shape

apiVersion: mas/v1
kind: Tool
metadata:
  name: web-search          # call name (required)
  description: Catalogue one-liner
spec:
  description: >            # LLM / tool-server description
    Search the web. Call this when the user needs current information.
  parameters:
    - name: query
      type: string
      required: true
  returns:                  # short daily-ops return note
    type: object
    description: Dict with query, results, cached
  impl:
    kind: python
    module_path: ./web_search_tool.py
    class_name: WebSearchTool

Annotated example with every optional advertise field: schemas/examples/tools/annotated.tool.yaml.

Required vs optional

Field Required Notes
metadata.name yes Call name (call_tool first argument)
spec.description no (default "") LLM-facing text
spec.parameters[] no (default []) JSON Schema properties
spec.impl.module_path yes when loading Hidden from the LLM
spec.returns no Short {type, description} — not a full JSON Schema
spec.idempotent no (default false) Retry hint
spec.timeout_seconds no (default 30) Wall-clock cap
spec.title no Display name distinct from metadata.name
spec.impl.kind no (default python) python, remote_tool, or openapi
spec.impl.module_path yes when loading Hidden from the LLM
spec.impl.class_name no (default null) Implementation class; may be auto-discovered
spec.impl.params no (default {}) Constructor arguments passed to the implementation
spec.output_schema no Full JSON Schema for the result (MCP outputSchema)
spec.read_only no Omit = unspecified, not false
spec.destructive no Omit = unspecified
spec.open_world no Omit = unspecified
spec.icons[] no {src, mime_type, sizes, theme}
spec.task_support no forbidden | optional | required
spec.meta no Advertise _meta for protocol adapters
spec.semantics no Trace/metrics interpretation (concept, op, subject_arg). Composite providers set this per list_tools() entry instead.
spec.execution_mode no (default sync) sync | async | realtime
spec.result_mode no (default inline) inline | stream | session
spec.events no Stream/session event descriptors
spec.tool_category no Catalogue grouping

read_only / destructive / open_world use three-state YAML: omit the key to leave the hint unspecified. false is an explicit hint.

What does not belong here

Connection and list-transport policy are infra, not the tool:

Concern Manifest
URL, SSE vs stdio, HTTP headers, call timeout for a remote server infra/v1 kind: ToolServerRegistry
Remote endpoint and protocol infra/v1 ToolServerRegistry
Implementation class spec.impl on this document

See infra.md — ToolServerRegistry.

Omitted keys

  • YAML may omit every optional key (additionalProperties: false rejects unknown keys only).
  • ToolDocument.from_dict defaults unset advertise fields to empty / None.
  • list_tools() returns {name, description, parameters} when optionals are unset. YAML extras are merged onto that dict when present. semantics is copied onto ExchangeRecord for traces and metrics; it is stripped before the LLM wire payload.

See also