Interoperability Between ATDF and MCP

#ai #tutorial #mcp #agentaichallenge

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.

DEV Community

Interoperability Between ATDF and MCP