OriginGrid

Search for AI agent information sources. Returns `structuredContent.sources[]` with {source_id, name, url, region, difficulty, score}. Read the array directly — no Markdown parsing. Then call origingrid_fetch for each source's URL to get actual content. [ASRP: Use FIRST to find sources. Then fetch each source.url.]

{
  "type": "object",
  "properties": {
    "limit": {
      "default": 5,
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "description": "Skip the first N results for pagination",
      "type": "integer"
    },
    "query": {
      "type": "string"
    }
  },
  "required": [
    "query"
  ]
}

Get details for a single information source by its source_id

{
  "type": "object",
  "properties": {
    "source_id": {
      "type": "string"
    }
  },
  "required": [
    "source_id"
  ]
}

List available information sources, optionally filtered by topic and/or region. Supports `limit`/`offset` pagination; the response reports the **total** number of matches so you can page through all results. [ASRP: Browse available sources by category. Use for exploration before planning.]

{
  "type": "object",
  "properties": {
    "limit": {
      "default": 10,
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "description": "Skip the first N results for pagination",
      "type": "integer"
    },
    "region": {
      "type": "string"
    },
    "topic": {
      "type": "string"
    }
  }
}

Submit a new URL as a source-card candidate (anonymous, pending review). [ASRP: Use AFTER finding a URL that is useful but not yet in the registry.]

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "url": {
      "type": "string"
    }
  },
  "required": [
    "url"
  ]
}

Fetch first-hand content from a URL. Returns `structuredContent.data` with {title, content, url, cache_hit, fetched_at}. Read `.data.content` directly — the metadata and content are separated. Pass `delivery_level=excerpt` (default) for ~300 chars, `full` for complete content. [ASRP: Call AFTER origingrid_search. Loop over sources[] and fetch each source.url.]

{
  "type": "object",
  "properties": {
    "delivery_level": {
      "default": "full",
      "description": "Content delivery level: full=complete, excerpt=~300 chars, title=only title",
      "enum": [
        "full",
        "excerpt",
        "title"
      ],
      "type": "string"
    },
    "query": {
      "type": "string"
    },
    "selector": {
      "description": "CSS selector to extract (default: body)",
      "type": "string"
    },
    "source_id": {
      "description": "Registered source id (local-index fallback)",
      "type": "string"
    },
    "timeout": {
      "description": "Fetch timeout in seconds (default: 20)",
      "type": "integer"
    },
    "url": {
      "description": "Direct URL to fetch live (first-hand content, cached locally)",
      "type": "string"
    }
  }
}

Get OriginGrid registry statistics

{
  "type": "object",
  "properties": {}
}

{
  "type": "object",
  "properties": {
    "total_contributions": {
      "type": "integer"
    },
    "total_searches": {
      "type": "integer"
    },
    "total_sources": {
      "type": "integer"
    },
    "total_users": {
      "type": "integer"
    }
  }
}

Find sources similar to a known source. [ASRP: Use AFTER finding a relevant source to expand your search scope before calling origingrid_plan.]

{
  "type": "object",
  "properties": {
    "limit": {
      "default": 5,
      "type": "integer"
    },
    "source_id": {
      "type": "string"
    }
  },
  "required": [
    "source_id"
  ]
}

Search sources filtered by region (cn/global/academic/etc) and optionally by query. [ASRP: Use for region-specific discovery. Narrower than origingrid_search, use when you know the target region.]

{
  "type": "object",
  "properties": {
    "limit": {
      "default": 10,
      "type": "integer"
    },
    "query": {
      "type": "string"
    },
    "region": {
      "type": "string"
    }
  },
  "required": [
    "region"
  ]
}

Approve a pending source-card contribution (admin only; requires admin_token when ORIGINGRID_ADMIN_TOKEN is set)

{
  "type": "object",
  "properties": {
    "admin_token": {
      "type": "string"
    },
    "contribution_id": {
      "type": "integer"
    }
  },
  "required": [
    "contribution_id"
  ]
}

Reject a pending source-card contribution (admin only; requires admin_token when ORIGINGRID_ADMIN_TOKEN is set). Optionally pass `reason`. Review loop: list pending → origingrid_approve_contribution(id) / origingrid_reject_contribution(id)

{
  "type": "object",
  "properties": {
    "admin_token": {
      "type": "string"
    },
    "contribution_id": {
      "type": "integer"
    },
    "reason": {
      "description": "Optional rejection reason (stored for the contributor)",
      "type": "string"
    }
  },
  "required": [
    "contribution_id"
  ]
}

List pending source-card contributions awaiting admin review (admin only; requires admin_token when ORIGINGRID_ADMIN_TOKEN is set). Review loop: list pending → origingrid_approve_contribution(id)

{
  "type": "object",
  "properties": {
    "admin_token": {
      "description": "Admin token (required only if ORIGINGRID_ADMIN_TOKEN is configured)",
      "type": "string"
    }
  }
}

Discover first-hand information sources for a topic from the OriginGrid local registry — no external search engine involved. Optionally narrow by topic and/or region. Follow up with origingrid_fetch(url) for live content or origingrid_get_source for details. [ASRP: Use FIRST for broad topic discovery. Follow with origingrid_plan for multi-step fetch or origingrid_fetch for single URL.]

{
  "type": "object",
  "properties": {
    "limit": {
      "default": 8,
      "type": "integer"
    },
    "query": {
      "description": "Topic or theme to discover sources for",
      "type": "string"
    },
    "region": {
      "description": "Optional region filter (e.g. cn, global, academic)",
      "type": "string"
    },
    "topic": {
      "description": "Optional topic/category filter (e.g. programming, finance)",
      "type": "string"
    }
  },
  "required": [
    "query"
  ]
}

Resolve a natural-language query into directly executable first-hand source URLs. Returns structured JSON with executable_url that the agent opens locally. Supports searchable sources (API/search URLs with query parameters) and navigable sources (key pages like about/products/docs/pricing). Does NOT proxy-fetch or submit URLs to general-purpose search engines. [ASRP: Lightweight alternative to plan+execute_batch. Use for direct URL resolution without multi-step plans. For complex queries, use origingrid_plan instead.]

{
  "type": "object",
  "properties": {
    "intent": {
      "description": "Explicit intent override (auto/about/products/docs/pricing/news/contact/search/academic/code). Default: auto-detect",
      "type": "string"
    },
    "limit": {
      "default": 5,
      "description": "Max results",
      "type": "integer"
    },
    "query": {
      "description": "Natural language query",
      "type": "string"
    },
    "region": {
      "description": "Optional region filter",
      "type": "string"
    },
    "topic": {
      "description": "Optional topic/category filter",
      "type": "string"
    }
  },
  "required": [
    "query"
  ]
}

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    },
    "resolved_intent": {
      "type": "string"
    },
    "results": {
      "type": "array"
    }
  }
}

Generate an executable search plan for an AI agent. Returns a structured JSON plan with ordered steps, each containing an executable URL with method, expected latency, difficulty, and priority. The agent executes the steps itself — no search-engine caching. Steps within the same parallel_group can be fetched concurrently. Requires browser for yellow-difficulty sources. [ASRP: Call AFTER search/discover. Pass the returned steps to origingrid_execute_batch for concurrent execution.]

{
  "type": "object",
  "properties": {
    "intent": {
      "description": "Explicit intent override (auto/about/products/docs/pricing/news/contact/search/academic/code). Default: auto-detect",
      "type": "string"
    },
    "max_sources": {
      "default": 5,
      "description": "Maximum number of plan steps to return (max 20)",
      "type": "integer"
    },
    "query": {
      "description": "Search query",
      "type": "string"
    },
    "timeout_hint": {
      "default": 30,
      "description": "Agent's max acceptable wait in seconds",
      "type": "integer"
    }
  },
  "required": [
    "query"
  ]
}

{
  "type": "object",
  "properties": {
    "parallel_groups": {
      "type": "array"
    },
    "plan_id": {
      "type": "string"
    },
    "query": {
      "type": "string"
    },
    "resolved_intent": {
      "type": "string"
    },
    "steps": {
      "type": "array"
    }
  }
}

Execute multiple search plan steps in batch. Accepts `steps` (array of step objects from origingrid_plan) and optional `parallel_groups` (array of arrays of step indices). Steps within the same parallel_group run concurrently on the server — the agent doesn't need to manage concurrency. Supports per-step timeout, automatic retry (default 1), and error isolation (one step failing doesn't affect others). Concurrency is limited to 8 by default for VPS memory safety. Returns structured results with elapsed timing per step. Combine with origingrid_plan: plan → execute_batch → agent reads the results. [ASRP: Call AFTER origingrid_plan. Steps in same parallel_group run concurrently.]

{
  "type": "object",
  "properties": {
    "batch_timeout": {
      "default": 90,
      "description": "Total batch timeout in seconds (max 90)",
      "type": "integer"
    },
    "parallel_groups": {
      "description": "Optional: groups of step indices to run in parallel. Each group waits for the previous to finish. Default: one step per group (serial).",
      "items": {
        "items": {
          "type": "integer"
        },
        "type": "array"
      },
      "type": "array"
    },
    "retry_count": {
      "default": 1,
      "description": "Number of retry attempts per step",
      "type": "integer"
    },
    "step_timeout": {
      "default": 30,
      "description": "Per-step timeout in seconds",
      "type": "integer"
    },
    "steps": {
      "description": "Array of step objects (from origingrid_plan steps)",
      "items": {
        "properties": {
          "difficulty": {
            "description": "Fetch difficulty",
            "enum": [
              "green",
              "yellow",
              "red"
            ],
            "type": "string"
          },
          "source_id": {
            "description": "Source identifier from plan",
            "type": "string"
          },
          "url": {
            "description": "URL to fetch",
            "type": "string"
          }
        },
        "required": [
          "url"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "steps"
  ]
}

{
  "type": "object",
  "properties": {
    "completed": {
      "type": "integer"
    },
    "concurrency_limit": {
      "type": "integer"
    },
    "failed": {
      "type": "integer"
    },
    "results": {
      "type": "array"
    },
    "total_elapsed_ms": {
      "type": "integer"
    }
  }
}

Create a search session that persists across multiple tool calls. Generates a plan and returns a session_id. Call origingrid_search_session_execute with this session_id to execute steps group by group. [ASRP: Use INSTEAD of origingrid_plan+execute_batch when you need persistent session state across calls.]

{
  "type": "object",
  "properties": {
    "intent": {
      "description": "Explicit intent override (auto/about/products/docs/pricing/news/contact/search/academic/code). Default: auto-detect",
      "type": "string"
    },
    "max_sources": {
      "default": 5,
      "description": "Maximum number of sources (max 20)",
      "type": "integer"
    },
    "query": {
      "description": "Search query",
      "type": "string"
    }
  },
  "required": [
    "query"
  ]
}

Execute the next unexecuted step group in a search session. Pass the session_id from origingrid_search_session_create. Returns results for the current group and reports remaining groups. [ASRP: Call AFTER origingrid_search_session_create. Repeat until remaining_groups is 0.]

{
  "type": "object",
  "properties": {
    "batch_timeout": {
      "default": 90,
      "description": "Total batch timeout in seconds (max 90)",
      "type": "integer"
    },
    "retry_count": {
      "default": 1,
      "description": "Number of retry attempts per step",
      "type": "integer"
    },
    "session_id": {
      "description": "Session ID from origingrid_search_session_create",
      "type": "string"
    },
    "step_timeout": {
      "default": 30,
      "description": "Per-step timeout in seconds",
      "type": "integer"
    }
  },
  "required": [
    "session_id"
  ]
}

Get the current status of a search session. Returns query, depth, completed/total groups, progress percentage, and timestamps. [ASRP: Use to check session progress between execute calls.]

{
  "type": "object",
  "properties": {
    "session_id": {
      "description": "Session ID from origingrid_search_session_create",
      "type": "string"
    }
  },
  "required": [
    "session_id"
  ]
}

Submit feedback (rating 1-5) for a source returned in a previous search, using that search's `search_id` (from origingrid_search response). Feeds source quality signals; rating 3 = neutral, no positive/negative bias.

{
  "type": "object",
  "properties": {
    "comment": {
      "description": "optional context",
      "type": "string"
    },
    "rating": {
      "description": "1=bad, 2=poor, 3=neutral, 4=good, 5=excellent",
      "maximum": 5,
      "minimum": 1,
      "type": "integer"
    },
    "search_id": {
      "description": "search_id from a previous origingrid_search response",
      "type": "integer"
    },
    "source_id": {
      "description": "source_id from the search results",
      "type": "string"
    }
  },
  "required": [
    "search_id",
    "source_id",
    "rating"
  ]
}