Interoperability Between ATDF and MCP

The Agent Tool Description Format (ATDF) is an open standard based on JSON/YAML for describing tools functionally—what a tool does, when to use it, and how to use it. In contrast, the Model Context Protocol (MCP) by Anthropic is an open protocol (using JSON-RPC 2.0) that standardizes how AI assistants (LLMs) discover and invoke external tools and data sources. While ATDF is a static format for tool descriptions, MCP defines a two-way mechanism ("hosts" and "clients") for listing and invoking tools at runtime. Note: MCP is officially called Model Context Protocol (not "Multimodal Callable Procedures"), though its design inherently supports "multimodal" calls. Describing MCP Tools in ATDF In MCP, each tool is defined as a JSON object with fields like name, description, inputSchema (parameter definitions in JSON Schema), and optional annotations (usage hints). For example, Anthropic’s official "fetch" server exposes a fetch tool with parameters: url (required string) raw (optional boolean). To describe this in ATDF, map these fields to: tool_id: Unique identifier (e.g., "fetch"). description: Brief explanation (e.g., "Retrieves and processes content from a URL"). when_to_use: Contextual usage (e.g., "When needing to fetch or analyze a webpage"). how_to_use.inputs: List of parameters with name, type, and description. how_to_use.outputs: Success/failure messages (ATDF-specific; MCP does not define these explicitly). Example ATDF Description for fetch: { "tool_id": "fetch", "description": "Retrieves and extracts content from a webpage given its URL", "when_to_use": "Use when you need to obtain or process content from a website", "how_to_use": { "inputs": [ { "name": "url", "type": "string", "description": "The URL of the page to retrieve" }, { "name": "raw", "type": "boolean", "description": "If true, returns raw HTML (default: false)" } ], "outputs": { "success": "Web content retrieved successfully", "failure": [ { "code": "invalid_url", "description": "The provided URL is invalid or inaccessible" }, { "code": "fetch_error", "description": "Error retrieving content" } ] } } } Key Similarities and Differences Aspect ATDF MCP Nature Static JSON/YAML format for tool descriptions Dynamic JSON-RPC protocol for tool discovery/invocation Identifier tool_id (unique string) name (unique string) Description description + when_to_use explain functionality and context description (optional free text); uses annotations for usage hints (e.g., readOnly) Parameters List in how_to_use.inputs (name, type, description) Defined in inputSchema (JSON Schema object) Outputs success/failure messages in how_to_use.outputs Free-form results returned during tools/call; no standardized output schema Usage Context Explicit when_to_use field Relies on agent logic or annotations; no dedicated field Communication N/A (static specification only) Uses tools/list and tools/call endpoints (JSON-RPC) Metadata Supports multilingual descriptions, versioning, tags (v0.2.0) No built-in multilingual metadata in the base protocol Design Focus Descriptive and functional; model-agnostic Integration-focused; orchestrates workflows between agents and external servers Examples, Documentation, and Community There are no official integrations between ATDF and MCP yet, but both have standalone resources: ATDF: GitHub repository with formal specs, JSON schemas, and examples. MCP: Official documentation and examples (e.g., fetch, analyze_csv, github_create_issue). Community efforts include: AutoGen: Integrates MCP via McpToolAdapter (converts tools to BaseTool objects). Víctor Dibia: Demonstrated MCP integration with AutoGen agents (e.g., fetch server). No public codebases automate MCP-to-ATDF conversion yet. Manual mapping or ad-hoc scripts are required. Approaches for Translating MCP to ATDF 1. Manual Mapping or Custom Scripts Write a script (e.g., Python) to: Map MCP fields to ATDF: name → tool_id description → description Parse inputSchema.properties to populate how_to_use.inputs. Validate with ATDF’s official Python SDK (pip install agent-tool-description-format). 2. Leverage SDKs MCP SDK: Use Python/TypeScript SDKs to dynamically fetch tools via tools/list. ATDF SDK: Serialize MCP data into ATDF using the Python SDK for validation. 3. Agent Frameworks (e.g., AutoGen) AutoGen’s McpToolAdapter converts MCP tools into executable objects. Extend this to serialize metadata into ATDF. 4. Validation and Refinement Validate generated ATDF with JSON schemas. Enhance fields like when_to_use or add multilingual metadata (ATDF v0.2.0). Conclusion While ATDF and MCP serve different purposes—ATDF for static tool descriptions and MCP for runtime communicat

May 9, 2025 - 07:12

The Agent Tool Description Format (ATDF) is an open standard based on JSON/YAML for describing tools functionally—what a tool does, when to use it, and how to use it. In contrast, the Model Context Protocol (MCP) by Anthropic is an open protocol (using JSON-RPC 2.0) that standardizes how AI assistants (LLMs) discover and invoke external tools and data sources. While ATDF is a static format for tool descriptions, MCP defines a two-way mechanism ("hosts" and "clients") for listing and invoking tools at runtime.

Note: MCP is officially called Model Context Protocol (not "Multimodal Callable Procedures"), though its design inherently supports "multimodal" calls.

Describing MCP Tools in ATDF

In MCP, each tool is defined as a JSON object with fields like name, description, inputSchema (parameter definitions in JSON Schema), and optional annotations (usage hints). For example, Anthropic’s official "fetch" server exposes a fetch tool with parameters:

url (required string)
raw (optional boolean).

To describe this in ATDF, map these fields to:

tool_id: Unique identifier (e.g., "fetch").
description: Brief explanation (e.g., "Retrieves and processes content from a URL").
when_to_use: Contextual usage (e.g., "When needing to fetch or analyze a webpage").
how_to_use.inputs: List of parameters with name, type, and description.
how_to_use.outputs: Success/failure messages (ATDF-specific; MCP does not define these explicitly).

Example ATDF Description for `fetch`:

{
  "tool_id": "fetch",
  "description": "Retrieves and extracts content from a webpage given its URL",
  "when_to_use": "Use when you need to obtain or process content from a website",
  "how_to_use": {
    "inputs": [
      { "name": "url", "type": "string", "description": "The URL of the page to retrieve" },
      { "name": "raw", "type": "boolean", "description": "If true, returns raw HTML (default: false)" }
    ],
    "outputs": {
      "success": "Web content retrieved successfully",
      "failure": [
        { "code": "invalid_url", "description": "The provided URL is invalid or inaccessible" },
        { "code": "fetch_error", "description": "Error retrieving content" }
      ]
    }
  }
}

Key Similarities and Differences

Aspect	ATDF	MCP
Nature	Static JSON/YAML format for tool descriptions	Dynamic JSON-RPC protocol for tool discovery/invocation
Identifier	`tool_id` (unique string)	`name` (unique string)
Description	`description` + `when_to_use` explain functionality and context	`description` (optional free text); uses `annotations` for usage hints (e.g., readOnly)
Parameters	List in `how_to_use.inputs` (name, type, description)	Defined in `inputSchema` (JSON Schema object)
Outputs	`success`/`failure` messages in `how_to_use.outputs`	Free-form results returned during `tools/call`; no standardized output schema
Usage Context	Explicit `when_to_use` field	Relies on agent logic or annotations; no dedicated field
Communication	N/A (static specification only)	Uses `tools/list` and `tools/call` endpoints (JSON-RPC)
Metadata	Supports multilingual descriptions, versioning, tags (v0.2.0)	No built-in multilingual metadata in the base protocol
Design Focus	Descriptive and functional; model-agnostic	Integration-focused; orchestrates workflows between agents and external servers

Examples, Documentation, and Community

There are no official integrations between ATDF and MCP yet, but both have standalone resources:

ATDF: GitHub repository with formal specs, JSON schemas, and examples.
MCP: Official documentation and examples (e.g., fetch, analyze_csv, github_create_issue).

Community efforts include:

AutoGen: Integrates MCP via McpToolAdapter (converts tools to BaseTool objects).
Víctor Dibia: Demonstrated MCP integration with AutoGen agents (e.g., fetch server).

No public codebases automate MCP-to-ATDF conversion yet. Manual mapping or ad-hoc scripts are required.

Approaches for Translating MCP to ATDF

1. Manual Mapping or Custom Scripts

Write a script (e.g., Python) to:

Map MCP fields to ATDF:
- name → tool_id
- description → description
- Parse inputSchema.properties to populate how_to_use.inputs.
Validate with ATDF’s official Python SDK (pip install agent-tool-description-format).

2. Leverage SDKs

MCP SDK: Use Python/TypeScript SDKs to dynamically fetch tools via tools/list.
ATDF SDK: Serialize MCP data into ATDF using the Python SDK for validation.

3. Agent Frameworks (e.g., AutoGen)

AutoGen’s McpToolAdapter converts MCP tools into executable objects. Extend this to serialize metadata into ATDF.

4. Validation and Refinement

Validate generated ATDF with JSON schemas. Enhance fields like when_to_use or add multilingual metadata (ATDF v0.2.0).

Conclusion

While ATDF and MCP serve different purposes—ATDF for static tool descriptions and MCP for runtime communication—they can complement each other. By mapping fields like name → tool_id and inputSchema → how_to_use.inputs, developers can create interoperable systems where agents dynamically invoke tools described in ATDF.