Skip to content

Natural Language Mode

!!! info "TL;DR" Describe what you want in plain English. Claude Sonnet parses your intent into structured tool calls. No JSON required.

How It Works

The MCP server includes an optional natural language mode. Instead of crafting precise JSON tool calls, you describe your goal conversationally. Claude Sonnet parses the intent and generates the appropriate tool calls.

Example: Survey Creation

You say:

"Create a 5-question NPS survey targeting users who signed up in the last 30 days. Ask about onboarding experience, feature discovery, and overall satisfaction."

Claude parses this into:

{
  "tool": "create_survey",
  "params": {
    "title": "New User Onboarding Experience",
    "description": "Help us improve onboarding for new users",
    "questions": [
      {
        "type": "nps",
        "text": "How likely are you to recommend us to a friend?",
        "required": true
      },
      {
        "type": "rating",
        "text": "How would you rate your onboarding experience?",
        "min_value": 1,
        "max_value": 5,
        "required": true
      },
      {
        "type": "multiple_choice",
        "text": "Which features did you discover during onboarding?",
        "options": [
          "Profile setup",
          "First interaction",
          "Settings customization",
          "Help documentation"
        ],
        "required": false
      },
      {
        "type": "text",
        "text": "What was the most confusing part of getting started?",
        "required": false
      },
      {
        "type": "rating",
        "text": "How satisfied are you overall?",
        "min_value": 1,
        "max_value": 5,
        "required": true
      }
    ],
    "targeting": {
      "user_segment": "created_at > now() - interval '30 days'"
    }
  }
}

The server then executes this tool call as if you had written the JSON yourself.

Enabling Natural Language Mode

Include mode: "natural_language" in your request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "mode": "natural_language",
    "input": "Create a 5-question NPS survey targeting users who signed up in the last 30 days"
  }
}

The server sends your input to Claude Sonnet with a specialized prompt that includes:

  • Available tools and their schemas
  • The agent's assigned scopes
  • Examples of well-formed tool calls

Claude responds with structured JSON that the server validates and executes.

What Gets Parsed

The NL parser handles:

  • Tool selection — "Create a survey" → create_survey
  • Parameter extraction — "5 questions" → questions: [...] with 5 items
  • Targeting rules — "users who signed up in the last 30 days" → user_segment filter
  • Question types — "NPS survey" → includes an NPS question type
  • Default inference — If you don't specify required/optional, Claude makes reasonable defaults

Limitations

Natural language mode works best for:

  • Creating surveys
  • Querying responses
  • Triggering workflows
  • Getting analytics

It's less suitable for:

  • Bulk operations (use direct tool calls)
  • Precise targeting rules (write SQL directly)
  • Complex conditional logic (define workflows explicitly)

For maximum control, use direct JSON tool calls. For exploratory work and one-off tasks, natural language is faster.

Cost Considerations

Each natural language request calls Claude Sonnet. This adds latency (typically 1-3 seconds) and cost (per Anthropic's API pricing).

For production workflows, parse once during development, then reuse the generated JSON. Natural language is best for:

  • Ad-hoc requests from product managers
  • Exploratory data analysis
  • Prototyping new workflows

Debugging

If Claude misinterprets your intent, the server returns an error with the parsed result:

{
  "error": {
    "code": -32602,
    "message": "Natural language parsing failed",
    "data": {
      "parsed_tool": "create_survey",
      "validation_error": "questions must be an array",
      "hint": "Try being more explicit about question types"
    }
  }
}

You can then refine your prompt or switch to direct JSON.

Examples

Create a Workflow

Natural language:

"When someone submits feedback with more than 10 votes, create a GitHub issue and send a Slack message to #product"

Parsed:

{
  "tool": "create_workflow",
  "params": {
    "name": "High-Vote Feedback to GitHub",
    "trigger": {
      "type": "vote_threshold",
      "conditions": {
        "threshold": 10
      }
    },
    "actions": [
      {
        "type": "create_github_issue",
        "params": {
          "repo": "Revoir-Software/revoir-apps",
          "labels": ["user-feedback"]
        }
      },
      {
        "type": "slack_notify",
        "params": {
          "channel": "#product",
          "message": "New high-vote feedback: {{submission.title}}"
        }
      }
    ]
  }
}

Query Responses

Natural language:

"Show me all negative survey responses from the last week"

Parsed:

{
  "tool": "list_responses",
  "params": {
    "start_date": "2026-02-03T00:00:00Z",
    "end_date": "2026-02-10T23:59:59Z",
    "filters": {
      "sentiment": "negative"
    }
  }
}

What's Next