Skip to content
Ctrl/⌘ K

MCP

MCP query builder tool

Build a typed search request with a stored BYOK model.

Overview

Build a complete typed Yep search request from natural language with a stored BYOK model. This does not execute search and bills one Agent API run after a valid build.

Use the typed search tools for web retrieval. Use list_models before BYOK query-builder or agent calls, and configure a provider key at the returned setup_url when requested. When a tool error's structured content includes error.validation, correct every listed RFC 6901 issue before retrying and never repeat an unchanged rejected input.

Input schema

MCP query builder tool input
Name
instruction
Required
Yes
Type
string
Description
Natural-language search goal.
Constraints
min length: 1; max length: 4096
Name
current_request
Required
No
Type
SearchPostRequest | null
Description
Optional request whose useful constraints should be preserved.
Constraints
Name
model
Required
Yes
Type
AgentModelRef
Description
Exact allowlisted BYOK model.
Constraints

Output schema

Returns structured JSON from the shared public API service.

MCP query builder tool output fields
Name
request
Required
Yes
Type
SearchPostRequest
Description
Complete public search request.
Name
canonical_filter
Required
No
Type
string | null
Description
Canonical text form of `request.filter`, when present.
Name
request_id
Required
Yes
Type
string
Description
Billing and support correlation identifier.

Tool errors

Tool execution failures set isError to true. When error.validation is present, correct every RFC 6901 issue before retrying and do not repeat unchanged input.

Request json 
{
  "error": {
    "code": "invalid_request",
    "reason": "malformed_request",
    "message": "invalid request: request body violates the public contract",
    "recovery": null,
    "agent_session_id": null,
    "validation": {
      "contract": "SearchPostRequest",
      "issues": [
        {
          "code": "required",
          "path": "/query",
          "suggestion": "Add the required `query` field."
        }
      ],
      "truncated": false
    }
  },
  "request_id": "00000000-0000-0000-0000-000000000000"
}

Behavior

This tool is state-changing or billable, non-destructive, and not idempotent.

Commands