Tool Responses¶

All Code Scalpel tools return a standardized response envelope with consistent structure.

Response Envelope¶

Every tool response follows this structure:

{
  "data": {
    // Tool-specific result data
  },
  "tier_applied": "community | pro | enterprise",
  "duration_ms": 123,
  "error": null
}

Envelope Fields¶

Field	Type	Description
`data`	object \| null	Tool-specific result data
`tier_applied`	string	Which tier was used for this request
`duration_ms`	integer	Execution time in milliseconds
`error`	object \| null	Error details if operation failed

Success Response¶

{
  "data": {
    "functions": [
      {"name": "process_order", "line": 45, "complexity": 8}
    ],
    "classes": [],
    "imports": ["os", "json"]
  },
  "tier_applied": "community",
  "duration_ms": 45,
  "error": null
}

Error Response¶

{
  "data": null,
  "tier_applied": "community",
  "duration_ms": 12,
  "error": {
    "code": "SYMBOL_NOT_FOUND",
    "message": "Function 'process_ordder' not found in file",
    "suggestion": "Did you mean 'process_order'?",
    "recovery_options": ["process_order", "process_orders", "handle_order"]
  }
}

Error Object Structure¶

Field	Type	Description
`code`	string	Error code identifier
`message`	string	Human-readable error message
`suggestion`	string \| null	Suggested fix or alternative
`recovery_options`	array \| null	List of valid alternatives
`file`	string \| null	Related file path
`line`	integer \| null	Related line number

Common Response Patterns¶

List Response¶

{
  "data": {
    "items": [...],
    "total": 42,
    "page": 1,
    "per_page": 20
  }
}

Analysis Response¶

{
  "data": {
    "summary": {...},
    "details": [...],
    "warnings": [...],
    "mermaid_diagram": "graph TD..."
  }
}

Extraction Response¶

{
  "data": {
    "extracted_code": "def foo(): ...",
    "token_count": 150,
    "dependencies": [...],
    "context": {...}
  }
}

Security Response¶

{
  "data": {
    "vulnerabilities": [...],
    "risk_level": "HIGH",
    "summary": {
      "critical": 1,
      "high": 2,
      "medium": 3
    }
  }
}

Tier Metadata¶

The response always indicates which tier was used:

{
  "tier_applied": "pro",
  "tier_limits": {
    "max_depth": 50,
    "max_nodes": 500
  },
  "was_limited": false
}

Tier Limit Exceeded¶

{
  "data": {...},
  "tier_applied": "community",
  "tier_limits": {
    "max_depth": 3,
    "max_nodes": 50
  },
  "was_limited": true,
  "limitation_warning": "Results truncated. Upgrade to Pro for full analysis."
}

Duration Tracking¶

duration_ms helps monitor performance:

{
  "duration_ms": 1250,
  "timing_breakdown": {
    "parse": 45,
    "analyze": 1100,
    "format": 105
  }
}

Partial Results¶

Some tools may return partial results:

{
  "data": {
    "complete_results": [...],
    "partial_results": [...],
    "incomplete_reason": "Timeout after 5000ms"
  },
  "status": "partial"
}

Streaming Responses¶

Long operations may stream progress:

// Progress notification
{
  "type": "progress",
  "progress": 50,
  "message": "Analyzing file 25/50..."
}

// Final result
{
  "type": "result",
  "data": {...}
}

Parsing Responses in Code¶

Python¶

import json

response = tool_call("analyze_code", {"code": code})
result = json.loads(response)

if result.get("error"):
    print(f"Error: {result['error']['message']}")
    if result['error'].get('suggestion'):
        print(f"Suggestion: {result['error']['suggestion']}")
else:
    data = result["data"]
    print(f"Found {len(data['functions'])} functions")

TypeScript¶

interface ToolResponse<T> {
  data: T | null;
  tier_applied: string;
  duration_ms: number;
  error: ErrorDetails | null;
}

interface ErrorDetails {
  code: string;
  message: string;
  suggestion?: string;
  recovery_options?: string[];
}

const response = await callTool<AnalysisResult>("analyze_code", { code });
if (response.error) {
  console.error(`Error: ${response.error.message}`);
} else {
  console.log(`Functions: ${response.data?.functions.length}`);
}

Best Practices¶

Always check for errors - Even successful responses may have warnings
Handle partial results - Long operations may time out
Monitor duration - Track performance over time
Use tier info - Display tier limitations to users
Parse recovery options - Offer alternatives on error