Output Formats

Bellwether supports multiple output formats for different use cases: documentation, CI/CD integration, and security scanning.

Available Formats

Format	File	Use Case
Markdown	AGENTS.md	Human-readable documentation
JSON	bellwether-report.json	Machine-readable data
SARIF	bellwether.sarif	GitHub Code Scanning
JUnit	junit.xml	CI test runners

Markdown (Default)

Human-readable behavioral documentation.

bellwether interview npx your-server
# Output: AGENTS.md

Example Output

# @modelcontextprotocol/server-filesystem

> Generated by Bellwether on 2026-01-12 using gpt-4o

## Overview

A file management server providing read/write access to the local filesystem.

## Tools

### read_file

Reads the contents of a file from the specified path.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| path | string | yes | Path to the file |

**Observed Behavior:**
- Returns file contents as UTF-8 text
- Binary files returned as base64
- Maximum file size: 10MB

**Error Handling:**
- `ENOENT`: File not found
- `EACCES`: Permission denied

**Limitations:**
- Cannot read outside root directory

**Security Considerations:**
- Path traversal normalized within root

## Quick Reference

| Tool | Signature |
|------|-----------|
| read_file | `read_file(path)` |
| write_file | `write_file(path, content)` |

## Performance

| Tool | Calls | Avg | P95 | Max | Errors |
|------|-------|-----|-----|-----|--------|
| read_file | 5 | 45ms | 120ms | 150ms | 0% |
| write_file | 3 | 89ms | 200ms | 250ms | 0% |

### Performance Insights
- All tools performing within acceptable limits

## Prompts

### summarize_file

Generates a summary of a file's contents.

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| path | string | yes | Path to the file to summarize |
| max_length | number | no | Maximum summary length |

**Expected Output:**
Returns a structured summary prompt message suitable for LLM processing.

**Behavior Notes:**
- Works best with text files under 50KB
- Returns error for binary files

The AGENTS.md output includes:

• Tool Profiles - Behavioral documentation for each tool
• Prompt Profiles - Documentation for prompts (if the server exposes any)
• Quick Reference - Tool signatures for easy lookup
• Performance Metrics - Response times and error rates for each tool

JSON Report

Machine-readable format for programmatic access.

bellwether interview --json npx your-server
# Output: bellwether-report.json

Example Output

{
  "version": 1,
  "timestamp": "2026-01-12T10:30:00Z",
  "server": {
    "name": "@modelcontextprotocol/server-filesystem",
    "version": "1.0.0"
  },
  "tools": [
    {
      "name": "read_file",
      "description": "Reads file contents",
      "schema": {
        "type": "object",
        "properties": {
          "path": { "type": "string" }
        },
        "required": ["path"]
      },
      "interview": {
        "questionsAsked": 3,
        "observations": [...],
        "errors": [...],
        "security": [...]
      }
    }
  ],
  "prompts": [
    {
      "name": "summarize_file",
      "description": "Generate a summary of file contents",
      "arguments": [
        { "name": "path", "required": true },
        { "name": "max_length", "required": false }
      ],
      "interview": {
        "questionsAsked": 2,
        "observations": [...],
        "errors": [...]
      }
    }
  ],
  "scenarioResults": [
    {
      "type": "tool",
      "name": "read_file",
      "description": "Read existing file",
      "passed": true,
      "assertions": [...]
    }
  ],
  "cost": {
    "tokens": 1234,
    "estimatedCost": 0.02
  }
}

The JSON report includes:

• tools and prompts arrays with their respective interview results
• scenarioResults array with custom scenario test results (if scenarios were run)

SARIF (Security)

Static Analysis Results Interchange Format for GitHub Code Scanning.

bellwether interview --output-format sarif -o ./results npx your-server
# Output: results/bellwether.sarif

Upload to GitHub

# .github/workflows/security.yml
- name: Run Bellwether Security Scan
  run: |
    bellwether interview \
      --preset security \
      --output-format sarif \
      -o ./results \
      npx your-server

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: ./results/bellwether.sarif

Example Output

{
  "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "Bellwether",
          "version": "0.2.0"
        }
      },
      "results": [
        {
          "ruleId": "security/path-traversal",
          "level": "warning",
          "message": {
            "text": "Potential path traversal vulnerability in read_file"
          }
        }
      ]
    }
  ]
}

JUnit XML

For CI test runners that expect JUnit format.

bellwether interview --output-format junit -o ./results npx your-server
# Output: results/junit.xml

Use with GitLab CI

bellwether:
  script:
    - bellwether interview --output-format junit -o ./results npx your-server
  artifacts:
    reports:
      junit: results/junit.xml

Example Output

<?xml version="1.0" encoding="UTF-8"?>
<testsuites name="Bellwether" tests="12" failures="1" time="45.2">
  <testsuite name="read_file" tests="3" failures="0">
    <testcase name="happy_path_read" time="2.1"/>
    <testcase name="error_handling_missing" time="1.8"/>
    <testcase name="security_path_traversal" time="3.2"/>
  </testsuite>
</testsuites>

Multiple Formats

Generate multiple formats in one run:

bellwether interview \
  --json \
  --output-format sarif \
  -o ./output \
  npx your-server

This creates:

• output/AGENTS.md
• output/bellwether-report.json
• output/bellwether.sarif

Custom Output Directory

bellwether interview -o ./docs npx your-server
# Output: docs/AGENTS.md

See Also

• CI/CD Integration - Using outputs in pipelines
• interview - Output options
• Drift Detection - Comparing outputs