> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runalloy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Response Handling

## Smart Response Management

The MCP Server automatically optimizes large responses for better performance and usability.

### When You'll See Different Responses

#### 1. Large Datasets (more than 50 items)

Instead of overwhelming the MCP client with hundreds of results, the server returns helpful guidance:

```json expandable theme={null}
{
  "needsRefinement": true,
  "message": "Found 298 users. This is too many to display effectively.",
  "guidance": "When dealing with large result sets, it's better to:\n1. Search for specific items by name or ID\n2. Use filtering parameters\n3. Paginate through results",
  "suggestions": [
    "Try: users_list with limit parameter (e.g., { limit: 10 })",
    "Search for specific users by email",
    "Filter by status or creation date"
  ],
  "searchInstructions": "You can search using:\n- query (query): Search by name\n- limit (query): Limit results (e.g., 10)",
  "samples": [
    { "id": "U123", "name": "John Doe", "email": "john@example.com" },
    { "id": "U124", "name": "Jane Smith", "email": "jane@example.com" }
  ]
}
```

#### 2. Medium Datasets (25-50 items)

Automatically limited with metadata:

```json theme={null}
{
  "data": [ /* First 25 items */ ],
  "metadata": {
    "originalCount": 45,
    "displayedCount": 25,
    "truncated": true,
    "paginationHint": "Showing first 25 of 45 items."
  }
}
```

#### 3. Normal Responses (less than 25 items)

Standard response with full data.

### Why This Matters

* **Better Performance**: Faster responses, less data transfer
* **Smarter Interactions**: The AI guides you to refine searches
* **Platform Limits**: Respects rate limits of external APIs

## Error Responses

All errors follow a consistent format:

```json theme={null}
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Human-readable error message",
    "details": {
      "field": "Additional context"
    }
  }
}
```

### Common Error Codes

| Code                   | Description                 | HTTP Status |
| :--------------------- | :-------------------------- | :---------- |
| `INVALID_REQUEST`      | Malformed request           | 400         |
| `UNAUTHORIZED`         | Invalid or missing auth     | 401         |
| `FORBIDDEN`            | Insufficient permissions    | 403         |
| `NOT_FOUND`            | Resource not found          | 404         |
| `RATE_LIMITED`         | Too many requests           | 429         |
| `INTERNAL_ERROR`       | Server error                | 500         |
| `CREDENTIAL_NOT_FOUND` | Platform credential missing | 400         |
| `CONNECTOR_NOT_FOUND`  | Invalid connector ID        | 404         |
| `ACTION_NOT_FOUND`     | Invalid action ID           | 404         |

### Error Context

Errors include contextual information to help debug issues:

```json theme={null}
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Credential not found for Slack",
    "data": {
      "connectorId": "slack",
      "suggestion": "Run get_credentials_alloy('slack') to check available credentials",
      "authUrl": "https://app.runalloy.com/oauth/slack"
    }
  },
  "id": 1
}
```

## Response Size Management

### Automatic Truncation

To prevent overwhelming responses:

* **Arrays**: Limited to 25 items by default
* **Strings**: Truncated at 5KB with ellipsis
* **Nested objects**: Deep nesting limited to 10 levels

### Elicitation Pattern

For large datasets, the server provides guidance instead of raw data:

```json expandable theme={null}
{
  "type": "elicitation",
  "totalItems": 500,
  "message": "Too many results to display. Please refine your search.",
  "availableFilters": ["status", "created_date", "name"],
  "examples": [
    "Search by name: {\"name\": \"John\"}",
    "Filter by status: {\"status\": \"active\"}",
    "Limit results: {\"limit\": 10}"
  ]
}
```

## Caching

Responses are cached for improved performance:

* **Cache TTL**: 1 hour for read operations
* **Cache Key**: Based on connector, action, and parameters
* **Cache Invalidation**: Automatic on write operations
* **Cache Headers**: `X-Cache-Hit: true` when served from cache

## Streaming Responses

For long-running operations, the server supports streaming:

```http theme={null}
Accept: text/event-stream
```

Streaming events:

```
event: progress
data: {"message": "Processing item 1 of 100"}

event: result
data: {"status": "complete", "result": {...}}
```