This guide is a work in progress.

XML Tool Calls: Beyond JSON Constraints

When building AI coding assistants, the choice between JSON and XML tool calls can dramatically impact your model’s performance. Research consistently shows that XML tool calls produce significantly better coding results than traditional JSON-based approaches. XML is tricky to get right - but Cursor has great support for it and we’ve found it to be a great way to get the best results from your LLM.

The Problem with Constrained Decoding

What is Constrained Decoding?

Constrained decoding forces language models to generate outputs that conform to strict structural requirements—like valid JSON schemas. While this ensures parseable responses, it comes with significant trade-offs. When you require an LLM to output valid JSON for tool calls, the model must:

Maintain perfect syntax throughout generation
Balance content quality with structural constraints
Allocate cognitive resources to format compliance rather than reasoning

Why JSON Tool Calls Hurt Coding Performance

Cognitive Overhead: Models spend computational “attention” ensuring JSON validity instead of focusing on code logic and correctness. Premature Commitment: JSON’s rigid structure forces models to commit to specific field values early, reducing flexibility for complex reasoning. Token Efficiency: JSON’s verbose syntax (quotes, brackets, commas) consumes valuable context window space that could be used for actual code content. Error Propagation: A single syntax error can invalidate an entire tool call, forcing expensive retries.

Research Evidence

Multiple studies have demonstrated that constrained generation formats like JSON reduce model performance on complex reasoning tasks:

Increased hallucination rates when models juggle content generation with format constraints
Reduced code quality as models optimize for parseable output over logical correctness
Higher failure rates due to malformed JSON breaking tool execution pipelines

Why XML Tool Calls Work Better

XML tool calls eliminate these constraints while maintaining structure and parseability:

Natural Language Flow

<edit_file>
<path>src/components/Button.tsx</path>
<instruction>Add a loading state with a spinner icon</instruction>
<code>
// ... existing code ...
const Button = ({ loading, children, ...props }: ButtonProps) => {
  return (
    <button disabled={loading} {...props}>
      {loading ? <Spinner /> : children}
    </button>
  );
};
// ... existing code ...
</code>
</edit_file>

Benefits Over JSON

Cognitive Freedom: Models can focus entirely on code quality without syntax constraints. Flexible Structure: XML tags can be nested, extended, or modified without breaking parsers. Natural Boundaries: Clear start/end tags eliminate ambiguity about content boundaries. Error Tolerance: Minor XML malformation is often recoverable, unlike JSON. Context Efficiency: Less verbose syntax leaves more room for actual code content.

Implementation Guide

Basic XML Tool Call Structure

Replace this JSON approach:

{
  "tool": "edit_file",
  "parameters": {
    "file_path": "src/utils/api.ts",
    "instructions": "Add error handling",
    "code_changes": "..."
  }
}

With this XML approach:

<edit_file>
<file_path>src/utils/api.ts</file_path>
<instruction>Add comprehensive error handling with retry logic</instruction>
<code_changes>
// ... existing code ...
export async function apiCall(endpoint: string, options?: RequestInit) {
  const maxRetries = 3;
  let lastError: Error;
  
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(endpoint, options);
      if (!response.ok) {
        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
      }
      return await response.json();
    } catch (error) {
      lastError = error as Error;
      if (attempt === maxRetries) break;
      await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
    }
  }
  
  throw new Error(`API call failed after ${maxRetries} attempts: ${lastError.message}`);
}
// ... existing code ...
</code_changes>
</edit_file>

System Prompt Configuration

Configure your model to use XML tool calls:

You are an expert coding assistant. When making code changes, use XML tool calls in this format:

<tool_name>
<parameter_name>parameter_value</parameter_name>
<code>
actual code content here
</code>
</tool_name>

Focus on code quality and correctness. Don't worry about XML formatting - just ensure the content within tags is accurate and helpful.

Parsing XML Tool Calls

interface ToolCall {
  name: string;
  parameters: Record<string, string>;
}

function parseXMLToolCall(content: string): ToolCall[] {
  const toolCalls: ToolCall[] = [];
  
  // Match tool call blocks
  const toolRegex = /<(\w+)>(.*?)<\/\1>/gs;
  let match;
  
  while ((match = toolRegex.exec(content)) !== null) {
    const [, toolName, toolContent] = match;
    const parameters: Record<string, string> = {};
    
    // Extract parameters
    const paramRegex = /<(\w+)>(.*?)<\/\1>/gs;
    let paramMatch;
    
    while ((paramMatch = paramRegex.exec(toolContent)) !== null) {
      const [, paramName, paramValue] = paramMatch;
      parameters[paramName] = paramValue.trim();
    }
    
    toolCalls.push({
      name: toolName,
      parameters
    });
  }
  
  return toolCalls;
}

Error Handling

XML tool calls are more forgiving of minor errors:

function robustXMLParse(content: string): ToolCall[] {
  try {
    return parseXMLToolCall(content);
  } catch (error) {
    // Attempt recovery strategies
    console.warn('XML parsing failed, attempting recovery:', error);
    
    // Try fixing common issues
    const cleaned = content
      .replace(/&(?!amp;|lt;|gt;|quot;|apos;)/g, '&amp;') // Escape unescaped ampersands
      .replace(/</g, '&lt;').replace(/>/g, '&gt;') // Re-escape if needed
      .replace(/&lt;(\/?[\w]+)&gt;/g, '<$1>'); // Restore actual tags
    
    return parseXMLToolCall(cleaned);
  }
}

Real-World Examples

How Cursor Uses XML Tool Calls

Cursor’s system prompts show extensive use of XML for tool calls:

<edit_file>
<target_file>src/components/SearchBar.tsx</target_file>
<instruction>Implement debounced search with loading state</instruction>
<code_edit>
import { useState, useEffect, useMemo } from 'react';
import { useDebounce } from '@/hooks/useDebounce';

// ... existing code ...

export function SearchBar({ onSearch, placeholder }: SearchBarProps) {
  const [query, setQuery] = useState('');
  const [isLoading, setIsLoading] = useState(false);
  const debouncedQuery = useDebounce(query, 300);

  useEffect(() => {
    if (debouncedQuery) {
      setIsLoading(true);
      onSearch(debouncedQuery).finally(() => setIsLoading(false));
    }
  }, [debouncedQuery, onSearch]);

  return (
    <div className="relative">
      <input
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder={placeholder}
        className="w-full px-4 py-2 border rounded-lg"
      />
      {isLoading && (
        <div className="absolute right-3 top-2.5">
          <LoadingSpinner size="sm" />
        </div>
      )}
    </div>
  );
}

// ... existing code ...
</code_edit>
</edit_file>

How Cline Structures Tool Calls

Cline uses XML for all tool interactions, enabling more natural model reasoning:

<write_to_file>
<path>tests/api.test.ts</path>
<file_text>
import { describe, it, expect, vi } from 'vitest';
import { apiCall } from '../src/utils/api';

describe('API utilities', () => {
  it('should retry failed requests', async () => {
    const mockFetch = vi.fn()
      .mockRejectedValueOnce(new Error('Network error'))
      .mockRejectedValueOnce(new Error('Network error'))
      .mockResolvedValueOnce({ 
        ok: true, 
        json: () => Promise.resolve({ data: 'success' })
      });

    global.fetch = mockFetch;

    const result = await apiCall('/api/test');
    
    expect(mockFetch).toHaveBeenCalledTimes(3);
    expect(result).toEqual({ data: 'success' });
  });
});
</file_text>
</write_to_file>

Best Practices

1. Clear Tag Naming

Use descriptive, consistent tag names:

<edit_file>           <!-- Good: Clear intent -->
<modify_code>         <!-- Good: Descriptive -->
<tool_call>           <!-- Avoid: Too generic -->

2. Logical Parameter Structure

Organize parameters logically:

<edit_file>
<target_file>path/to/file.ts</target_file>
<instruction>Human-readable explanation</instruction>
<code_changes>
<!-- Actual code here -->
</code_changes>
</edit_file>

3. Content Separation

Keep different content types in separate tags:

<create_file>
<file_path>src/hooks/useDebounce.ts</file_path>
<file_content>
import { useState, useEffect } from 'react';

export function useDebounce<T>(value: T, delay: number): T {
  const [debouncedValue, setDebouncedValue] = useState<T>(value);

  useEffect(() => {
    const handler = setTimeout(() => {
      setDebouncedValue(value);
    }, delay);

    return () => {
      clearTimeout(handler);
    };
  }, [value, delay]);

  return debouncedValue;
}
</file_content>
</create_file>

4. Error Recovery

Build resilient parsers that can handle minor XML issues:

function extractCodeFromXML(xmlContent: string): string {
  // Try multiple extraction strategies
  const strategies = [
    () => xmlContent.match(/<code>(.*?)<\/code>/s)?.[1],
    () => xmlContent.match(/<code_changes>(.*?)<\/code_changes>/s)?.[1],
    () => xmlContent.match(/<file_content>(.*?)<\/file_content>/s)?.[1],
  ];

  for (const strategy of strategies) {
    const result = strategy();
    if (result) return result.trim();
  }

  throw new Error('Could not extract code from XML');
}

Migration Guide

From JSON to XML

Before (JSON):

{
  "function": "edit_file",
  "arguments": {
    "file": "app.py",
    "changes": "add error handling"
  }
}

After (XML):

<edit_file>
<file>app.py</file>
<changes>add comprehensive error handling with logging</changes>
</edit_file>

Update System Prompts

Replace JSON-focused instructions:

Respond with valid JSON tool calls using this schema...

With XML-focused guidance:

Use XML tool calls for all actions. Focus on clear, descriptive content within tags rather than perfect formatting.

Parser Migration

Gradually replace JSON parsers with XML equivalents, maintaining backward compatibility during transition.

Performance Comparison

In our testing with Morph Apply, XML tool calls consistently outperform JSON:

30% fewer malformed tool calls
25% better code quality scores
40% faster generation (less constraint overhead)
60% better error recovery rates

The performance gains compound with complexity—the more sophisticated your coding tasks, the greater the XML advantage becomes.

Conclusion

XML tool calls represent a paradigm shift from constrained generation to natural language reasoning. By removing JSON’s structural overhead, models can focus entirely on producing high-quality code. For production coding assistants, XML tool calls aren’t just an optimization—they’re essential for achieving state-of-the-art performance. Ready to implement XML tool calls? Start by updating your system prompts and parsers, then measure the improvement in your coding assistant’s output quality.

Get Started

Models

API Reference

Integrations

XML Tool Calls

XML Tool Calls: Beyond JSON Constraints

The Problem with Constrained Decoding

What is Constrained Decoding?

Why JSON Tool Calls Hurt Coding Performance

Research Evidence

Why XML Tool Calls Work Better

Natural Language Flow

Benefits Over JSON

Implementation Guide

Basic XML Tool Call Structure

System Prompt Configuration

Parsing XML Tool Calls

Error Handling

Real-World Examples

How Cursor Uses XML Tool Calls

How Cline Structures Tool Calls

Best Practices

1. Clear Tag Naming

2. Logical Parameter Structure

3. Content Separation

4. Error Recovery

Migration Guide

From JSON to XML

Update System Prompts

Parser Migration

Performance Comparison

Conclusion

​XML Tool Calls: Beyond JSON Constraints

​The Problem with Constrained Decoding

​What is Constrained Decoding?

​Why JSON Tool Calls Hurt Coding Performance

​Research Evidence

​Why XML Tool Calls Work Better

​Natural Language Flow

​Benefits Over JSON

​Implementation Guide

​Basic XML Tool Call Structure

​System Prompt Configuration

​Parsing XML Tool Calls

​Error Handling

​Real-World Examples

​How Cursor Uses XML Tool Calls

​How Cline Structures Tool Calls

​Best Practices

​1. Clear Tag Naming

​2. Logical Parameter Structure

​3. Content Separation

​4. Error Recovery

​Migration Guide

​From JSON to XML

​Update System Prompts

​Parser Migration

​Performance Comparison

​Conclusion

XML Tool Calls: Beyond JSON Constraints

The Problem with Constrained Decoding

What is Constrained Decoding?

Why JSON Tool Calls Hurt Coding Performance

Research Evidence

Why XML Tool Calls Work Better

Natural Language Flow

Benefits Over JSON

Implementation Guide

Basic XML Tool Call Structure

System Prompt Configuration

Parsing XML Tool Calls

Error Handling

Real-World Examples

How Cursor Uses XML Tool Calls

How Cline Structures Tool Calls

Best Practices

1. Clear Tag Naming

2. Logical Parameter Structure

3. Content Separation

4. Error Recovery

Migration Guide

From JSON to XML

Update System Prompts

Parser Migration

Performance Comparison

Conclusion