MCP Tools Reference

Complete schema and examples for all Neatlogs MCP tools. Includes parameters, responses, and error cases.

Complete reference for all tools exposed via the Neatlogs MCP server. Each tool is configurable and can be enabled/disabled via tools.yaml.

All tools return JSON-RPC 2.0 formatted responses. See Response Format section at the end for the standard envelope. Tool schemas show the inner result content.

Tool Categories

Category	Tools	Purpose
Connection	ping, whoami	Verify connectivity and authentication
Observability	search_traces, get_trace_context, list_detections, get_detection_trend	Query production data and trends
Logging	log_trace	Push traces from agents into Neatlogs
Fixes/Triage	triage_list, triage_get, triage_accept, triage_dismiss, triage_update_status, triage_update, triage_get_investigation, triage_list_steps	Read and manage code fixes

Connection Tools

These tools verify connectivity and authentication. Call them first to confirm your connection is working before using data-fetching tools.

ping

Health check. Always enabled and requires no parameters.

Input: None

Response:

{
  "status": "ok",
  "server_time": "2026-06-05T14:32:10Z"
}

Use cases:

Verify the MCP server is reachable
Periodic health monitoring
Confirm connectivity before other operations

whoami

Returns the project ID and organization this session is authenticated as.

Input: None

Response:

{
  "project_id": "proj_abc123def456",
  "org_id": "org_xyz789",
  "project_name": "My App"
}

Use cases:

Confirm authentication is working
Verify session scope and project binding
Log project context for debugging

These tools let you query production data. Use search_traces for broad queries, get_trace_context to dive into execution details, and list_detections/get_detection_trend to understand what's being monitored.

search_traces

Full-text search over production traces. Matches against trace names, error messages, span names, and metadata.

Input:

{
  "query": "string (required) - Search terms, e.g. 'timeout' or 'error rate'",
  "limit": "number (optional, default 50) - Max results to return, clamped to 100",
  "offset": "number (optional, default 0) - Pagination offset",
  "filters": {
    "framework": "string (optional) - LangChain, CrewAI, LangGraph, etc.",
    "status": "string (optional) - success, error",
    "min_latency_ms": "number (optional)",
    "max_latency_ms": "number (optional)",
    "min_cost": "number (optional) - In dollars",
    "max_cost": "number (optional)",
    "date_range": "string (optional) - last_24h, last_7d, last_30d, or ISO 8601 range"
  }
}

Response:

{
  "traces": [
    {
      "trace_id": "tr_xyz789abc123",
      "name": "process_customer_request",
      "status": "error",
      "created_at": "2026-06-05T14:30:00Z",
      "latency_ms": 5234,
      "error_message": "Timeout waiting for API response",
      "cost": 0.0234,
      "framework": "LangChain",
      "agent_name": "customer_service_agent",
      "url": "https://neatlogs.com/traces/tr_xyz789abc123"
    }
  ],
  "total_count": 147,
  "has_more": true
}

Errors:

400: Invalid filter (e.g., malformed date range)
429: Rate limited

Use: Find traces matching a search criteria. Use offsets for pagination.

get_trace_context

Fetch the complete execution tree for a trace, including all spans with inputs, outputs, and code locations.

Input:

{
  "trace_id": "string (required) - UUID of the trace"
}

Response:

{
  "trace_id": "tr_xyz789abc123",
  "name": "process_request",
  "status": "error",
  "created_at": "2026-06-05T14:30:00Z",
  "root_span": {
    "span_id": "sp_root001",
    "span_type": "WORKFLOW",
    "name": "process_request",
    "status": "error",
    "latency_ms": 5234,
    "start_time": "2026-06-05T14:30:00Z",
    "input": {
      "customer_id": "cust_123",
      "query": "What are my recent orders?"
    },
    "output": null,
    "error": "Timeout after 30 seconds",
    "metadata": {
      "model": "claude-3-opus",
      "tokens_used": 450
    },
    "children": [
      {
        "span_id": "sp_llm001",
        "span_type": "LLM",
        "name": "initial_analysis",
        "status": "success",
        "latency_ms": 2100,
        "input": {
          "prompt": "Analyze the following query..."
        },
        "output": "The user wants recent order history.",
        "metadata": {
          "model": "claude-3-opus",
          "input_tokens": 200,
          "output_tokens": 50
        }
      },
      {
        "span_id": "sp_tool001",
        "span_type": "TOOL",
        "name": "fetch_orders",
        "status": "error",
        "latency_ms": 3000,
        "input": {
          "customer_id": "cust_123"
        },
        "output": null,
        "error": "Connection timeout",
        "metadata": {
          "tool_name": "database_query",
          "retry_count": 2
        }
      }
    ]
  },
  "span_count": 12,
  "total_latency_ms": 5234,
  "total_cost": 0.0234
}

Errors:

404: Trace not found
400: Invalid trace ID format

Use: Analyze execution details, debug errors, understand span hierarchy.

list_detections

List all active detection types and their current statistics.

Input:

{
  "framework": "string (optional) - Filter by framework (LangChain, CrewAI, etc.)",
  "limit": "number (optional, default 50)"
}

Response:

{
  "detections": [
    {
      "name": "hallucination",
      "display_name": "Hallucination",
      "description": "Model output contains false or fabricated information",
      "severity": "high",
      "fire_count_24h": 14,
      "fire_count_7d": 89,
      "last_fired": "2026-06-05T13:45:00Z",
      "enabled": true
    },
    {
      "name": "prompt_regression",
      "display_name": "Prompt Regression",
      "description": "Quality drop compared to historical baseline",
      "severity": "high",
      "fire_count_24h": 3,
      "fire_count_7d": 12,
      "last_fired": "2026-06-05T11:20:00Z",
      "enabled": true
    },
    {
      "name": "cost_anomaly",
      "display_name": "Cost Anomaly",
      "description": "Token usage or cost spike above baseline",
      "severity": "medium",
      "fire_count_24h": 0,
      "fire_count_7d": 2,
      "last_fired": "2026-06-03T08:15:00Z",
      "enabled": true
    }
  ],
  "total_count": 18,
  "active_count": 18
}

Errors:

400: Invalid framework filter

Use: See what issues are being monitored and their frequency.

get_detection_trend

Get occurrence trend for a single detection (hourly or daily breakdown).

Input:

{
  "detection_name": "string (required) - e.g. 'hallucination', 'prompt_regression'",
  "granularity": "string (optional, default 'day') - 'hour' or 'day'",
  "date_range": "string (optional, default 'last_7d') - 'last_24h', 'last_7d', 'last_30d', or ISO 8601 range"
}

Response:

{
  "detection_name": "hallucination",
  "granularity": "day",
  "date_range": "2026-05-30 to 2026-06-05",
  "trend": [
    {
      "timestamp": "2026-05-30",
      "count": 8,
      "percentage_of_all_traces": 2.3
    },
    {
      "timestamp": "2026-05-31",
      "count": 12,
      "percentage_of_all_traces": 3.1
    },
    {
      "timestamp": "2026-06-01",
      "count": 5,
      "percentage_of_all_traces": 1.2
    },
    {
      "timestamp": "2026-06-05",
      "count": 14,
      "percentage_of_all_traces": 4.2
    }
  ],
  "total_count": 89,
  "avg_per_day": 12.7
}

Errors:

400: Invalid detection name or date range
404: Detection not found

Use: Track detection frequency over time, identify trending issues.

Logging Tools

Use log_trace when your agent completes a task and wants to record its execution. This lets you track what the agent did, how long it took, and any errors that occurred.

log_trace

Push an execution trace from an agent directly into Neatlogs. Useful for agents reporting their own work.

Input:

{
  "name": "string (required) - Trace name, e.g. 'agent_research_task'",
  "trace_id": "string (optional) - UUID; auto-generated if omitted",
  "spans": [
    {
      "span_id": "string (required) - UUID for this span",
      "parent_span_id": "string (optional) - UUID of parent",
      "name": "string (required) - Span name",
      "span_type": "string (required) - WORKFLOW, LLM, TOOL, AGENT, etc.",
      "status": "string (required) - success or error",
      "input": "object (optional) - Input data",
      "output": "object (optional) - Output data",
      "error": "string (optional) - Error message if status is error",
      "latency_ms": "number (optional) - Duration in milliseconds",
      "metadata": {
        "model": "string (optional) - Model name",
        "tokens_used": "number (optional)",
        "framework": "string (optional)"
      },
      "start_time": "string (optional) - ISO 8601 timestamp"
    }
  ],
  "metadata": {
    "framework": "string (optional) - LangChain, CrewAI, custom, etc.",
    "agent_name": "string (optional)"
  }
}

Response:

{
  "trace_id": "tr_abc123def456",
  "span_count": 5,
  "status": "created",
  "url": "https://neatlogs.com/traces/tr_abc123def456"
}

Errors:

400: Missing required fields or invalid span structure
413: Payload too large (max 1 MB)

Use: Agent reports completion, including execution details and errors.

Triage/Fix Tools

These tools manage the fix workflow. Start with triage_list to see what needs review, use triage_get to understand the root cause, then progress through triage_accept → triage_update_status → resolved as you deploy fixes.

triage_list

List all fixes (formerly called suggestions) for the project.

Input:

{
  "status": "string (optional) - draft, open, in_progress, resolved, archived",
  "severity": "string (optional) - critical, high, medium, low",
  "label": "string (optional) - prompt_regression, cost_anomaly, hallucination, etc.",
  "limit": "number (optional, default 50)",
  "offset": "number (optional, default 0)"
}

Response:

{
  "fixes": [
    {
      "id": "fix_xyz789abc123",
      "title": "Prompt returns inconsistent results",
      "description": "Quality has dropped 15% since last week",
      "status": "draft",
      "severity": "high",
      "label": "prompt_regression",
      "confidence": 92,
      "created_at": "2026-06-05T10:30:00Z",
      "updated_at": "2026-06-05T13:45:00Z",
      "creator": "neatlogs_ai",
      "linked_traces": ["tr_abc123", "tr_def456"],
      "dispatch_status": null
    }
  ],
  "total_count": 47,
  "has_more": true
}

Use: See all fixes, filter by status or severity.

triage_get

Get detailed information for a single fix.

Input:

{
  "fix_id": "string (required) - UUID of the fix"
}

Response:

{
  "id": "fix_xyz789abc123",
  "title": "Prompt returns inconsistent results",
  "description": "Quality has dropped 15% since last week",
  "status": "draft",
  "severity": "high",
  "label": "prompt_regression",
  "confidence": 92,
  "root_cause": "System prompt was updated without validation. New version produces less deterministic outputs.",
  "recommended_action": "Revert system prompt to previous version and run validation tests.",
  "risk_assessment": "Low risk. Reverting is quick. Previous version was stable.",
  "verification": "Run accuracy benchmark suite. Target: >95% accuracy (current: 80%)",
  "rollback_plan": "If issues persist, fall back to v1.2.3 of the prompt library.",
  "linked_traces": [
    {
      "trace_id": "tr_abc123def456",
      "name": "customer_query_1",
      "accuracy": 0.78,
      "url": "https://neatlogs.com/traces/tr_abc123def456"
    }
  ],
  "created_at": "2026-06-05T10:30:00Z",
  "updated_at": "2026-06-05T13:45:00Z",
  "creator": "neatlogs_ai",
  "dispatch_status": null,
  "comments": []
}

Errors:

404: Fix not found

Use: Review root cause and recommended action before accepting or dispatching.

triage_accept

Accept a draft fix, moving it to the Kanban board for visibility.

Input:

{
  "fix_id": "string (required) - UUID of the fix"
}

Response:

{
  "id": "fix_xyz789abc123",
  "status": "open",
  "updated_at": "2026-06-05T14:00:00Z"
}

Errors:

404: Fix not found
400: Fix is not in draft status

Use: Acknowledge a fix and make it visible to the team.

triage_dismiss

Dismiss a fix as false positive or not relevant.

Input:

{
  "fix_id": "string (required) - UUID of the fix",
  "reason": "string (optional) - Why it's dismissed (for feedback)"
}

Response:

{
  "id": "fix_xyz789abc123",
  "status": "archived",
  "updated_at": "2026-06-05T14:02:00Z"
}

Errors:

404: Fix not found
400: Fix already resolved or archived

Use: Remove false positives and help Neatlogs learn what's not relevant.

triage_update_status

Move a fix through the workflow: draft → open → in_progress → resolved → archived.

Input:

{
  "fix_id": "string (required) - UUID of the fix",
  "status": "string (required) - in_progress, resolved, archived",
  "note": "string (optional) - Status update note"
}

Response:

{
  "id": "fix_xyz789abc123",
  "status": "resolved",
  "updated_at": "2026-06-05T14:05:00Z",
  "note": "Fix deployed to production, monitoring for regressions"
}

Errors:

404: Fix not found
400: Invalid status transition

Use: Track fix progress through your workflow.

triage_update

Edit fix fields: title, severity, label, or recommended action.

Input:

{
  "fix_id": "string (required)",
  "title": "string (optional) - New title",
  "severity": "string (optional) - critical, high, medium, low",
  "label": "string (optional) - Categorization label",
  "recommended_action": "string (optional) - Updated action plan"
}

Response:

{
  "id": "fix_xyz789abc123",
  "title": "Revert prompt to v1.2.3 and validate",
  "severity": "critical",
  "updated_at": "2026-06-05T14:07:00Z"
}

Errors:

404: Fix not found
400: Invalid field value

Use: Refine fix details after further investigation.

triage_get_investigation

Get the investigation context thread for a fix.

Input:

{
  "fix_id": "string (required) - UUID of the fix"
}

Response:

{
  "fix_id": "fix_xyz789abc123",
  "investigation": {
    "created_at": "2026-06-05T10:30:00Z",
    "steps": [
      {
        "step_id": "step_1",
        "timestamp": "2026-06-05T10:30:00Z",
        "agent": "neatlogs_ai",
        "action": "Analyzed 24-hour trace history",
        "finding": "Error rate increased from 2% to 18% after 2:00 PM"
      },
      {
        "step_id": "step_2",
        "timestamp": "2026-06-05T10:35:00Z",
        "agent": "neatlogs_ai",
        "action": "Compared with system changes",
        "finding": "System prompt was updated at 2:00 PM by auto-deploy"
      }
    ]
  },
  "comments": [
    {
      "id": "comment_1",
      "author": "alice@company.com",
      "text": "This matches the behavior we saw last quarter.",
      "created_at": "2026-06-05T11:00:00Z"
    }
  ]
}

Errors:

404: Fix not found

Use: Review the investigation thread and team comments.

triage_list_steps

List investigation steps for a fix (alias of triage_get_investigation.steps).

Input:

{
  "fix_id": "string (required) - UUID of the fix",
  "limit": "number (optional, default 50)"
}

Response:

{
  "fix_id": "fix_xyz789abc123",
  "steps": [
    {
      "step_id": "step_1",
      "timestamp": "2026-06-05T10:30:00Z",
      "agent": "neatlogs_ai",
      "action": "Analyzed 24-hour trace history",
      "finding": "Error rate increased from 2% to 18%"
    },
    {
      "step_id": "step_2",
      "timestamp": "2026-06-05T10:35:00Z",
      "agent": "neatlogs_ai",
      "action": "Root cause analysis",
      "finding": "Prompt change at 2:00 PM correlates with spike"
    }
  ],
  "total_count": 2
}

Errors:

404: Fix not found

Use: Follow Neatlogs AI's investigation steps.

Configuration & Tuning

All tools respect timeout_ms settings in backend/config/tools.yaml. Default timeout is 15 seconds. Adjust per tool if needed:

tools:
  search_traces:
    timeout_ms: 30000  # Increase for complex queries
  get_detection_trend:
    timeout_ms: 20000  # Multi-day trends may take longer

Response Format

All tool responses follow the MCP JSON-RPC 2.0 format:

Success:

{
  "jsonrpc": "2.0",
  "id": <request-id>,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "<result-json>"
      }
    ]
  }
}

Error:

{
  "jsonrpc": "2.0",
  "id": <request-id>,
  "error": {
    "code": -32603,
    "message": "Internal error",
    "data": {
      "error": "Detailed error message"
    }
  }
}

Limits & Quotas

Be aware of these limits when designing your integrations. The 60 req/min rate limit is shared across all sessions for a single API key.

Limit	Value	Notes
Max request payload	1 MB	Total JSON size
Max response payload	10 MB	Truncated if exceeded
Search results per request	100	Use pagination for more
Trace context max depth	1000 spans	Very large traces may be truncated
Rate limit	60 requests/minute	Per API key, all sessions combined
Session timeout	1 hour of inactivity	Auto-cleanup on timeout
Max concurrent sessions per key	Unlimited	But respect rate limits

MCP Tools Reference

Tool Categories

Connection Tools

ping

whoami

Observability Tools

search_traces

get_trace_context

list_detections

get_detection_trend

Logging Tools

log_trace

Triage/Fix Tools

triage_list

triage_get

triage_accept

triage_dismiss

triage_update_status

triage_update

triage_get_investigation

triage_list_steps

Configuration & Tuning

Response Format

Limits & Quotas

See Also

On this page