venn（venn 搜索）

Venn Tools

Connect to enterprise SaaS tools through the Venn platform REST API.

Setup

This skill is gated on VENN_API_KEY — it won't appear until the key is set.

1. Get your API key from app.venn.ai

1. Add it to the OpenClaw .env file:

   echo 'VENN_API_KEY=your-api-key-here' >> ~/.openclaw/.env

1. Restart the gateway (picks up the new env on start):

   openclaw gateway restart

Or, for zero-downtime reload without restart:

   openclaw secrets reload

Alternatively, use the interactive secrets helper:

openclaw secrets configure --skip-provider-setup

Sandboxed agents: The .env file injects into the host process only. For sandboxed (Docker) sessions, also add VENN_API_KEY to agents.defaults.sandbox.docker.env in openclaw.json, or bake it into your custom sandbox image.

Configuration

• VENN_API_KEY (required) — your Venn API key
• VENN_API_URL (optional) — defaults to https://app.venn.ai/api/tooliq

Request Format

All requests use POST with JSON. Examples below use this shorthand:

# Full form (shown once):
VENN_URL="${VENN_API_URL:-https://app.venn.ai/api/tooliq}"
curl -s -X POST "${VENN_URL}/tools/search" \
  -H "Authorization: Bearer ${VENN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"query": "..."}'

# Shorthand (used throughout):
# POST /tools/search {"query": "..."}

1. Discovery

List connected servers

# POST /tools/help
{"action": "list_servers"}

Returns result.servers[] with server_id, name, and connection_status.

Other help actions:

• getting_started — onboarding guidance
• connector_help — info on connectors (pass server_id for specific one)
• auth_helper — OAuth re-auth URL for disconnected server (requires server_id)

Search for tools

# POST /tools/search
{"query": "jira search issues", "limit": 10}

Returns result.candidates[] with server_id, tool_name, short_description, and (for top results) full inputSchema.

Additional parameters: offset, min_score (0–1, default 0.3), min_results (default 5), include_skills (default true).

Search strategy — broad first, narrow if needed:

1. Start with the full task description in natural language (skills match better):

- "create a linear ticket and set it to in progress" - "sync salesforce contacts to a google sheet"

1. If no skill matches, decompose into one search per platform + action:

- "query salesforce contacts" + "create google sheets row"

1. For simple single-platform tasks, search directly: "create salesforce lead"

Splitting rules:

• 1 search = 1 platform + 1 action (no single tool handles compound actions)
• Always include the app name in each query
• "recap"/"summarize" → search the platform, then present
• "cross-reference"/"compare" → search each platform, combine results
• "sync X to Y" → search source, then destination

If no results, try alternate names:

• "jira" → "atlassian"
• "google docs" → "google-drive" or "googledocs"
• "github" → "github-cloud"

Choosing from results:

• Read operations → prefer broad query tools over get-by-ID
• Create/update → look for specific create/update endpoints
• If a skill appears (type="skill"), prefer it over assembling tools
• inputSchema is the source of truth for parameter names — NEVER guess

For platform-specific query syntax (JQL, SOQL, Gmail search), see references/query-syntax.md.

Describe a tool

# POST /tools/describe
{"tools": [{"server_id": "SERVER_ID", "tool_name": "TOOL_NAME"}]}

Supports batch requests. Returns result.results[] with inputSchema, description, and write_operation type.

2. Execution

Schema adherence (most common source of errors)

1. Copy parameter names verbatim from inputSchema — casing matters

- Schema says maxResults → use maxResults, NOT max_results

1. Match data types exactly:

- "type": "string" → "10", NOT 10 - "type": "integer" → 10, NOT "10" - "type": "array" → ["value"], NOT "value" - "type": "object" → {"key": "value"}, NOT "key=value"

1. Include all required fields. Do not add fields not in the schema.

Execute a single tool

# POST /tools/execute
{"server_id": "SERVER_ID", "tool_name": "TOOL_NAME", "tool_args": {...}}

Translating user intent into values (infer rather than ask):

• "recent tickets" → reasonable date range (e.g., last 7 days)
• "my emails" → userId: "me"
• "the main channel" → search for it by name first
• "current sprint" → the active sprint

This applies to values only — parameter names and types must come from inputSchema.

Data integrity: NEVER fabricate data. Only present what appears in actual responses.

Handling links: For create/edit operations, surface clickable URLs from fields like url, link, href, web_url, permalink, html_url. Present as [Resource Name](url).

Execute a workflow (multi-step)

Chain multiple tool calls in a Python sandbox:

# POST /tools/execute-workflow
{
  "code": "results = call_tool(\"atlassian\", \"searchByJQL\", jql=\"assignee = currentUser() AND status != Done\")\
return [{\"key\": i[\"key\"], \"summary\": i[\"fields\"][\"summary\"]} for i in results.get(\"issues\", [])]",
  "timeout": 180
}

When to use workflows:

• Multiple tool calls in sequence
• Parallel execution across services
• Data processing, iteration, or transformation

Code rules:

• Follow schema adherence rules above
• Write flat, inline code — no helper functions
• Code must return a value; extract only needed fields
• Check for errors: if isinstance(result, dict) and "error" in result: ...
• For pagination, loop until no more nextPageToken/cursor

Available in sandbox:

• call_tool(server_id, tool_name, **kwargs) — sequential
• async_call_tool(server_id, tool_name, **kwargs) — for asyncio.gather()
• call_skill(skill_id, inputs_dict) / async_call_skill(...) — call skills
• Modules: asyncio, json, datetime, math, re, collections, itertools, functools, operator, decimal, uuid, base64, hashlib
• No network, filesystem, or subprocess access
• No augmented assignment on subscripts: use d[k] = d[k] + 1, NOT d[k] += 1

3. Write Operation Confirmation

Write/delete operations return an audit response instead of executing. To proceed:

1. Show the operation summary to the user and wait for explicit approval

1. Get a confirmation token (expires in 60s):

   # POST /tools/confirm
   {"server_id": "SERVER_ID", "tool_name": "TOOL_NAME"}

1. Re-send with the token:

   # POST /tools/execute
   {"server_id": "...", "tool_name": "...", "tool_args": {...}, "confirmed": true, "confirmation_token": "TOKEN"}

Never call confirm without user's typed approval ("yes", "confirm", "proceed").

4. Skills

Skills are pre-built workflow patterns in search results with type: "skill". Prefer skills over assembling individual tools.

Executable skills

Marked executable: true. Run step-by-step:

# POST /tools/execute
{"tool_name": "SKILL_ID", "tool_args": {"step_id": "FIRST_STEP", "inputs": {...}}}

Each step returns outputs and next. If next is not null, read next.reasoning, fill placeholders, make the next call.

Guidance skills

For skills without executable: true, describe to get the pattern:

# POST /tools/describe
{"tools": [{"tool_name": "SKILL_NAME"}]}

Returns tools_involved, all_servers_connected, disconnected_servers, and step-by-step content. If all_servers_connected is false, use help(action="auth_helper") first.

5. Error Recovery

If a tool call fails, debug and retry — do not report failure immediately.

Only report failure after at least three different approaches have been tried.

Guardrails

• Start with list_servers or search to discover what's connected
• Always have inputSchema before executing (from search or describe)
• Match parameter names and types exactly
• Never fabricate data — only present actual responses
• Never execute writes without explicit user approval
• Prefer workflows for multi-step operations
• Prefer skills over assembling individual tools
• Pass session_id and user_intent on calls for tracing (API generates one if omitted)