Skip to content

TOON Format

Jump to bottom
Jeremy edited this page Nov 16, 2025 · 1 revision

TOON Format - Enhanced Response Formatting

TOON (Text-Optimized Output Notation) provides improved readability for Cisco API responses with structured JSON formatting.

Table of Contents

Overview

TOON Format is an enhanced response formatting system that converts raw Cisco API JSON responses into more readable, structured text output with embedded JSON blocks. This makes responses easier to read and process, especially in MCP clients like Claude Desktop.

Key Features

  • Structured Headers: Clear section titles and organization
  • Embedded JSON: Well-formatted JSON code blocks
  • Better Readability: Human-friendly text with technical details
  • Preserved Data: Full API response data retained in JSON blocks
  • Automatic Formatting: Enabled by default for all tools

What is TOON?

TOON stands for Text-Optimized Output Notation, a response formatting convention that combines:

  1. Human-Readable Text: Descriptive headers and summaries
  2. Structured JSON Blocks: Formatted code blocks with full data
  3. Contextual Information: Additional details and metadata

Standard Format vs TOON Format

Standard JSON Response (without TOON):

{"bugs":[{"bug_id":"CSCvi12345","headline":"Memory leak in CallManager","severity":"3","status":"O"}],"total_results":1}

TOON Formatted Response (with TOON):

Found 1 bug(s)

Bug ID: CSCvi12345
Headline: Memory leak in CallManager
Severity: 3
Status: O (Open)

Full API Response:
```json
{
  "bugs": [
    {
      "bug_id": "CSCvi12345",
      "headline": "Memory leak in CallManager",
      "severity": "3",
      "status": "O"
    }
  ],
  "total_results": 1
}


---

## Benefits

### 1. Improved Readability

TOON format makes responses easier to scan and understand:

- **Clear Structure**: Headers and sections guide the reader
- **Formatted JSON**: Proper indentation and syntax highlighting
- **Contextual Details**: Additional information beyond raw data

### 2. Better MCP Client Experience

MCP clients like Claude Desktop render TOON responses more effectively:

- **Markdown Rendering**: Headers and code blocks displayed properly
- **Syntax Highlighting**: JSON blocks with color coding
- **Easier Navigation**: Section headers create visual hierarchy

### 3. Preserved Raw Data

Despite human-friendly formatting, all raw data is preserved:

- **Full API Response**: Complete JSON embedded in code blocks
- **Programmatic Access**: LLMs can still parse JSON from responses
- **No Data Loss**: All fields and values from Cisco APIs retained

### 4. Consistent Format

All tool responses follow the same TOON structure:

- **Predictable Layout**: Same format across all tools
- **Standard Sections**: Summary, details, and raw JSON
- **Easier Parsing**: Consistent patterns for extraction

---

## Example Output

### Bug Search Response

**Without TOON** (raw JSON):
```json
{"bugs":[{"bug_id":"CSCvk12345","headline":"Router crashes on firmware upgrade","severity":"2","status":"F","product":"ISR4431","affected_releases":["16.12.04"],"fixed_releases":["17.3.1"]}],"total_results":1}

With TOON (formatted):

# Bug Search Results

Found 1 bug(s) for your query.

## Bug ID: CSCvk12345

**Headline:** Router crashes on firmware upgrade
**Severity:** 2 (High)
**Status:** F (Fixed)
**Product:** ISR4431

### Affected Releases
- 16.12.04

### Fixed Releases
- 17.3.1

### Full API Response
```json
{
  "bugs": [
    {
      "bug_id": "CSCvk12345",
      "headline": "Router crashes on firmware upgrade",
      "severity": "2",
      "status": "F",
      "product": "ISR4431",
      "affected_releases": ["16.12.04"],
      "fixed_releases": ["17.3.1"]
    }
  ],
  "total_results": 1
}


### Security Advisory Response

**Without TOON** (raw JSON):
```json
{"advisories":[{"advisory_id":"cisco-sa-20180221-ucdm","sir":"Critical","cve":["CVE-2018-0101"],"summary":"Cisco ASA Buffer Overflow Vulnerability"}]}

With TOON (formatted):

# Security Advisory

## Advisory ID: cisco-sa-20180221-ucdm

**Severity:** Critical
**CVE:** CVE-2018-0101
**Summary:** Cisco ASA Buffer Overflow Vulnerability

### Full Advisory Response
```json
{
  "advisories": [
    {
      "advisory_id": "cisco-sa-20180221-ucdm",
      "sir": "Critical",
      "cve": ["CVE-2018-0101"],
      "summary": "Cisco ASA Buffer Overflow Vulnerability"
    }
  ]
}


### Software Version Comparison

**With TOON** (formatted):

Software Version Comparison

Comparing versions for C9300-24P

Version A: 17.9.1 Version B: 17.12.3

Bug Analysis

  • Bugs in 17.9.1 only: 12 bugs
  • Bugs in 17.12.3 only: 3 bugs (all fixes)
  • Fixed in upgrade: 12 bugs resolved

Recommendation

✅ Recommended: Upgrade from 17.9.1 to 17.12.3

  • Resolves 12 known issues
  • Only 3 new issues (all severity 5-6)
  • Net improvement in stability

Full Comparison Data

{
  "product_id": "C9300-24P",
  "version_a": "17.9.1",
  "version_b": "17.12.3",
  "bugs_in_a": 12,
  "bugs_in_b": 3,
  "recommendation": "upgrade"
}

---

## Configuration

TOON format is **enabled by default** for all tools. No configuration needed.

### Environment Variables

```bash
# TOON is enabled by default
# No environment variable needed

# To disable TOON (see next section)
DISABLE_TOON_FORMAT=true

Default Behavior

  • All Tools: TOON formatting applied to all tool responses
  • All APIs: Bug, Case, EoX, PSIRT, Product, Software, Serial, RMA
  • All Modes: stdio and HTTP transport

Disabling TOON

To disable TOON and return raw JSON responses, set the environment variable:

In .env File

# Disable TOON format, return raw JSON
DISABLE_TOON_FORMAT=true

In Claude Desktop Config

{
  "mcpServers": {
    "cisco-support": {
      "command": "npx",
      "args": ["-y", "mcp-cisco-support"],
      "env": {
        "CISCO_CLIENT_ID": "your_client_id",
        "CISCO_CLIENT_SECRET": "your_secret",
        "SUPPORT_API": "all",
        "DISABLE_TOON_FORMAT": "true"
      }
    }
  }
}

In Docker

docker run -d \
  -e DISABLE_TOON_FORMAT=true \
  -e CISCO_CLIENT_ID=your_id \
  -e CISCO_CLIENT_SECRET=your_secret \
  ghcr.io/sieteunoseis/mcp-cisco-support:latest

Programmatic Disable

When calling tools via HTTP API:

# With TOON disabled
curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_bugs_by_keyword",
      "arguments": {"keyword": "crash"}
    }
  }'

When to Disable TOON

Consider disabling TOON format in these scenarios:

1. Programmatic Integration

If you're parsing responses programmatically:

# Python integration example
import json

# With TOON disabled, you get clean JSON
response = mcp_client.call_tool("search_bugs_by_keyword", {"keyword": "crash"})
bugs = json.loads(response)  # Direct JSON parsing

# With TOON enabled, you'd need to extract JSON from markdown
# (still possible, but requires additional parsing)

2. Custom Formatting

If you want to apply your own formatting:

// JavaScript integration
const response = await mcpClient.callTool('get_bug_details', {
  bug_ids: 'CSCvi12345'
});

// With TOON disabled, apply custom formatting
const formatted = customFormatter(JSON.parse(response));

3. Data Export

If you're exporting data to external systems:

# Export to file without markdown formatting
DISABLE_TOON_FORMAT=true mcp-cisco-support --http

# Pipe raw JSON to jq for processing
curl -X POST http://localhost:3000/mcp \
  -d '{"method":"tools/call","params":{"name":"search_bugs"}}' \
  | jq '.result.bugs[]'

4. Testing and Debugging

For automated testing with strict JSON validation:

// Jest test expecting strict JSON
test('bug search returns valid JSON', async () => {
  const response = await searchBugs('crash');
  expect(() => JSON.parse(response)).not.toThrow();
});

Keep TOON Enabled For:

  • ✅ Claude Desktop usage - Best reading experience
  • ✅ Manual queries - Easier to scan results
  • ✅ Interactive exploration - Better UX
  • ✅ Report generation - Already formatted nicely

TOON Implementation Details

Response Structure

All TOON responses follow this pattern:

# [Tool Name] Results

[Human-readable summary]

## [Section Headers]

[Formatted details]

### Full API Response
```json
{
  [Complete raw data]
}


### Markdown Features Used

- **Headers** (`#`, `##`, `###`) - Section hierarchy
- **Code Blocks** (` ```json `) - Syntax highlighting
- **Bold** (`**text**`) - Emphasis on key fields
- **Lists** (`-`, `1.`) - Structured data
- **Tables** (`|---|---|`) - Tabular data (when applicable)

### JSON Formatting

TOON applies these JSON formatting rules:

- **Indentation**: 2 spaces
- **Sorted Keys**: Alphabetical when beneficial
- **Pretty Print**: Multi-line with proper nesting
- **Valid JSON**: Always parseable with standard JSON parsers

---

## Comparison: TOON vs Raw JSON

| Aspect | TOON Format | Raw JSON |
|--------|-------------|----------|
| **Readability** | ⭐⭐⭐⭐⭐ Excellent | ⭐⭐ Limited |
| **MCP Client Rendering** | ⭐⭐⭐⭐⭐ Optimized | ⭐⭐ Basic |
| **Programmatic Access** | ⭐⭐⭐ Requires extraction | ⭐⭐⭐⭐⭐ Direct |
| **Data Preservation** | ⭐⭐⭐⭐⭐ Complete | ⭐⭐⭐⭐⭐ Complete |
| **File Size** | ⭐⭐⭐ Moderate | ⭐⭐⭐⭐ Compact |
| **Human Scanning** | ⭐⭐⭐⭐⭐ Fast | ⭐⭐ Slow |
| **Machine Parsing** | ⭐⭐⭐ JSON extraction needed | ⭐⭐⭐⭐⭐ Direct parsing |

---

## Future Enhancements

Planned improvements to TOON format:

- **Conditional Formatting**: Different formats based on data size
- **Customizable Templates**: User-defined TOON templates
- **Streaming Support**: Progressive TOON rendering for large results
- **Format Negotiation**: Client-specified format preferences
- **HTML Output**: Alternative to Markdown for web clients

---

## Next Steps

- [Advanced Configuration](Advanced-Configuration) - Environment variables and fine-tuning
- [Available Tools](Available-Tools) - Complete tool reference with examples
- [Development Guide](Development-Guide) - Architecture and customization

---

**Last Updated:** November 15, 2025 | **Version:** 1.18.0

Clone this wiki locally