codex-search-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@codex-search-mcpsearch the web for the latest SpaceX Starship launch news"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
codex-search-mcp
A Model Context Protocol (MCP) server providing real-time live web search, readable page extraction, market data, weather forecasts, sports schedules, and alpha browser tools powered by the reversed Codex / ChatGPT backend.
Designed to be instantly runnable with npx in Claude Desktop, Cursor, Windsurf, Oh My Pi, Cline, and any MCP client.
🚀 Features
Live Web Search (
web-search): Real-time web search queries returning titles, snippets, source URLs, and citations.Native Page Fetch (
fetch): Extracts clean, readable text/markdown from web pages without raw HTML noise.Deep Web Navigation (
open-page,click-link,find-in-page): Inspect pages, follow numbered reference links, and search text patterns.Live Market & Financial Data (
finance): Real-time stock, crypto, ETF, and index quotes with intraday changes and market caps.Weather Forecasts (
weather): Accurate 7-day weather forecasts and current conditions for any global location.Sports Schedules & Standings (
sports): Schedules and standings across leagues (NBA, EPL, NFL, MLB, NHL, etc.).Global World Time (
world-time): Instant, accurate time lookup for any UTC offset.PDF Screenshots (
screenshot-pdf): Extract high-resolution visual screenshots of PDF pages by page index.Image Search (
image-search): Query image search engine with optional domain and recency filters.Zero-Configuration Authentication: Automatically detects and refreshes credentials from
~/.codex/auth.json, environment variables, or interactive OAuth login.
Related MCP server: mcp-web-search-server
📦 Quick Start
Run directly without installation:
npx -y codex-search-mcpInteractive Login (Optional)
If you have a ChatGPT/Codex subscription and want to authenticate automatically:
npx codex-search-mcp loginThis starts the OAuth device code flow, shows a one-time verification URL and code, and securely stores the credentials in ~/.codex/auth.json (auto-refreshed upon expiration).
🛠MCP Client Configuration
Claude Desktop
Add the following to your claude_desktop_config.json:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"codex-search": {
"command": "npx",
"args": ["-y", "codex-search-mcp"],
"env": {
"CODEX_API_KEY": "your_api_key_here"
}
}
}
}(Note: If you have already authenticated with npx codex-search-mcp login or have ~/.codex/auth.json, you can omit the "env" block!)
Cursor
Add to your Cursor MCP settings (Settings -> Features -> MCP):
Name:
codex-searchType:
commandCommand:
npx -y codex-search-mcp
Oh My Pi (OMP)
Add to your ~/.omp/agent/mcp.toml:
[mcpServers.codex-search]
command = "npx"
args = ["-y", "codex-search-mcp"]🔑 Authentication Options
codex-search-mcp looks for authentication in the following order:
Environment Variables:
CODEX_API_KEY: API key for Codex or an OpenAI-compatible / LiteLLM proxy.OPENAI_API_KEY: Standard OpenAI API key.CODEX_BASE_URL(optional): Custom endpoint URL (e.g.https://litellm.v-rail.org/v1).
Existing Codex Configuration (
~/.codex/auth.json):Automatically detects access and refresh tokens created by the Codex CLI or
npx codex-search-mcp login.Expired tokens are refreshed automatically in the background.
🧰 Available Tools
Tool | Description | Arguments |
| Live internet search for queries, benchmark figures, and news |
|
| Fetch clean readable content from a list of URLs |
|
| Open page and position viewport at specific line |
|
| Follow a numbered reference link from an opened page |
|
| Search text or regex patterns in opened page |
|
| Capture PDF page screenshot |
|
| Search image engine |
|
| Financial quotes for stocks, crypto, ETFs, and indices |
|
| Weather forecast and current conditions |
|
| Sports schedules and league standings |
|
| Accurate time lookup by UTC offset |
|
💻 Development
git clone https://github.com/MintOcha/codex-search-mcp.git
cd codex-search-mcp
npm install
npm run build
npm test📄 License
MIT © MintOcha
Available Tools
11 toolsclick-linkC
Open the link link_id (numbered reference link) from previously opened page ref_id.
| Name | Required | Description | Default |
|---|---|---|---|
| ref_id | Yes | Previously opened page ref_id or URL | |
| link_id | Yes | Numeric link id found in page content |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full behavioral burden. It discloses the prerequisite that the page must already be open, but says nothing about side effects, whether navigation replaces the current page, or what is returned/available afterward (no output schema either).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the action, no filler text. It is appropriately sized, though the parenthetical aside is slightly awkward rather than wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a navigation tool with zero annotations and no output schema, the description should explain what clicking produces (new content, a new ref_id, navigation behavior). Only the input prerequisite is covered, leaving the result of the action unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description roughly restates the schema's meaning of link_id as a numbered reference link and ref_id as a prior page, adding at most marginal clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Open') and resource ('link'), and qualifies it as a numbered reference link within an already-opened page, which helps separate it from sibling open-page/fetch. The phrase 'link link_id' is slightly circular wording, but the intent is still clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies the link must come from a previously opened page, but never states when an agent should prefer this over open-page, fetch, or web-search, nor any exclusions. The only implicit guidance is the prerequisite ref_id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
fetchC
Fetch readable page content for given URLs using Codex native page extraction.
| Name | Required | Description | Default |
|---|---|---|---|
| urls | Yes | List of URLs to fetch readable content from |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It implies a read-only extraction ('readable page content', 'native page extraction'), which is useful, but says nothing about batch size limits, handling of non-HTML/JS-heavy pages, error behavior, or whether content is truncated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One tight sentence with the verb and resource front-loaded and no filler. It is efficient, though it leaves no room for the routing guidance the agent actually needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, no-output-schema utility this is minimally adequate: the core operation is stated. Missing is any differentiation from similar retrieval siblings and any note on limits or edge cases, which matters given the crowded sibling set.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single 'urls' array parameter, so the schema already documents format and meaning. The description's plural 'URLs' matches the array but adds no syntax or constraint detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Fetch) and resource (readable page content for given URLs), which is clear on its own. However, it never differentiates itself from the sibling 'open-page' or 'click-link', so an agent cannot tell from this text alone which page-retrieval tool to pick.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no indication of when to use this versus 'open-page', 'click-link', or 'web-search', nor any prerequisites or exclusions. Usage must be inferred entirely by the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
financeC
Look up financial quotes for a given ticker (type: equity, fund, crypto, index).
| Name | Required | Description | Default |
|---|---|---|---|
| market | No | Optional market exchange | |
| ticker | Yes | Ticker symbol (e.g. NVDA, AAPL, BTC) | |
| asset_type | No | Asset category | equity |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not disclose quote freshness (real-time vs delayed), market-hours behavior, rate limits, or failure modes for invalid tickers — all material for a financial quote tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One efficient sentence with the core action front-loaded and the parenthetical scope qualifier tacked on. No filler, though the enum repetition is marginally redundant with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-parameter read tool with a fully documented schema and no output schema, the description is minimally adequate. It still leaves the agent without quote-freshness or output-shape expectations, which matters for financial data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description restates the asset_type enum values (equity, fund, crypto, index) and the ticker concept but adds no meaning beyond the schema and completely omits the 'market' parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('look up') and resource ('financial quotes') plus the accepted asset categories, so an agent can tell it apart from unrelated siblings like weather or web-search. It is clear but does not name or contrast with any sibling explicitly, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, no prerequisites, no alternatives. It never says when a quote lookup is appropriate versus general web search for financial data, which a generic name like 'finance' invites confusion about.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
find-in-pageC
Find text pattern in page indicated by ref_id or URL.
| Name | Required | Description | Default |
|---|---|---|---|
| ref_id | Yes | URL or page reference ID | |
| pattern | Yes | Regex or text pattern to locate |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden but provides little behavioral context. It doesn't state whether the search is case-sensitive, how matches are returned (e.g., list of locations), or if it's read-only. Only basic purpose is conveyed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description is too sparse. It doesn't explain return values, behavior on no matches, or how it differs from similar sibling tools, leaving significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters (ref_id and pattern). The description mentions 'text pattern' and 'ref_id or URL' but adds no extra meaning beyond the schema, making baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: finding text patterns in a page identified by ref_id or URL. It's clear what the tool does, though it doesn't differentiate itself from siblings like fetch or open-page beyond the text-finding aspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., page must be loaded) or exclusions, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
image-searchC
Query image search engine for a given query.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Image search query | |
| domains | No | Filter results to specific domains | |
| recency_days | No | Filter by recency in days |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, yet it says nothing about what is returned (image URLs, thumbnails, metadata), rate limits, or result volume. It implies a read-only query but does not disclose any operational traits beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler or redundancy. It is efficient, though the trailing 'for a given query' is slightly circular with the required 'query' parameter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 3-parameter search tool with full schema coverage and no annotations, the description is minimally adequate. It omits any mention of result format, which no output schema covers, leaving a small but real gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so 'query', 'domains', and 'recency_days' are already documented in the schema. The description adds no additional meaning about the query syntax or how domain/recency filters interact, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a clear verb ('Query') and a specific resource ('image search engine'), which distinguishes it from the sibling web-search by domain. However, it does not name or explicitly contrast against any sibling, relying on the name alone to carry differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to choose this tool over web-search, fetch, or open-page, nor any statement of prerequisites or constraints. The agent is left to infer usage entirely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
open-pageB
Open the page indicated by ref_id or URL and position viewport at line lineno.
| Name | Required | Description | Default |
|---|---|---|---|
| lineno | No | Line number to position viewport at | |
| ref_id | Yes | URL or page reference ID |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It implies a viewport/browser context via 'position viewport at line lineno', which is a useful hint, but it says nothing about side effects, whether navigation replaces the current page, or any permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler; the action, target, and the optional lineno behavior are all stated compactly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description covers the mechanics adequately. However, it omits the provenance of ref_id and its relationship to sibling page-navigation tools, which an agent needs to invoke it correctly in sequence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented in the schema. The description restates the same semantics (ref_id as URL/reference, lineno as viewport target) without adding format details such as whether ref_id must be a search-result handle.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Open') and resource ('the page indicated by ref_id or URL') and adds the viewport-positioning behavior, so an agent knows exactly what action is taken. It stops short of distinguishing this from siblings like 'fetch' or 'click-link', which could plausibly also retrieve page content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no indication of when to prefer this over 'fetch', 'web-search', or 'click-link', nor any prerequisites (e.g. that ref_id typically comes from a prior search). Usage context is left entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
screenshot-pdfC
Take a screenshot of page pageno (0-indexed) indicated by ref_id or URL (works on PDFs).
| Name | Required | Description | Default |
|---|---|---|---|
| pageno | Yes | 0-indexed page number | |
| ref_id | Yes | PDF URL or reference ID |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, yet it says nothing about the return type (image bytes, URL, base64), required permissions, rate limits, or whether rendering large pages is expensive. Only the 0-indexing convention and PDF support are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact sentence with the operation front-loaded and the key constraint (0-indexed, PDF support) parenthetically noted. No filler, though the phrasing 'page pageno' is slightly awkward.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and no annotations means the description should explain what a screenshot call returns and any page-state preconditions, but it omits both. An agent cannot tell whether the result is an image blob or a link, nor how ref_id is obtained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both pageno (0-indexed) and ref_id (PDF URL or reference ID) are already fully documented in the schema. The description restates the same facts rather than adding format examples or constraints, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a concrete verb (take a screenshot) and a specific resource scope (a single PDF page identified by ref_id or URL). It distinguishes the operation from generic page tools by noting it works on PDFs, though it does not name which sibling to prefer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to choose this over siblings like open-page, fetch, or find-in-page, nor any prerequisite (e.g., must the PDF be opened/fetched first, where does ref_id come from). Usage must be inferred entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
sportsB
Look up sports schedules and standings (league: nba, wnba, nfl, nhl, mlb, epl, ncaamb, ncaawb, ipl; fn: schedule or standings).
| Name | Required | Description | Default |
|---|---|---|---|
| fn | No | Query type: schedule or standings | schedule |
| team | No | Optional team filter | |
| league | Yes | League code (e.g. nba, epl, nfl) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, yet it says nothing about data freshness, whether results are live or cached, rate limits, or the shape of the response. It discloses only the valid input domains (leagues, fn values).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence, front-loaded with the action and resource, with the enumerated values tucked into a parenthetical. No filler, though the packed parenthetical makes it slightly harder to scan than a structured breakdown.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter read tool with a required league, no output schema, and no annotations, the description covers the input contract adequately but omits what a response contains, whether team filtering applies to standings as well as schedules, and any data-source or freshness context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline would be 3, but the description adds value by enumerating the full set of nine accepted league codes and the two fn values, whereas the schema only samples 'e.g. nba, epl, nfl'. This materially reduces the chance of an invalid league value being passed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb ('look up') and resources ('sports schedules and standings'), plus the exact league codes and query types, which rescues the otherwise-vague tool name 'sports'. It does not distinguish itself from siblings like web-search or finance, but the resource is unambiguous once read.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to use this tool versus alternatives such as web-search or open-page, and no prerequisites or exclusions. Usage is only inferable from the enumerated leagues and fn values, leaving the agent to guess why it should not simply search the web for a score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
weatherC
Look up weather forecast for location (e.g. 'City, Country').
| Name | Required | Description | Default |
|---|---|---|---|
| location | Yes | Location name, city, or coordinates | |
| start_date | No | Start date (YYYY-MM-DD) | |
| duration_days | No | Duration in days |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It says to look up a forecast but does not state whether the operation is read-only, what data source or coverage is used, how location resolution works, or what the return format looks like, leaving key behavioral traits opaque.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. The example is embedded efficiently and nothing distracts from the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description is too minimal. It omits what the forecast includes, how start_date and duration_days shape the result, and when an agent should prefer this over web-search or other siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters are already documented in the input schema. The description adds a helpful example format ('City, Country') for the location parameter, but it adds no further meaning for start_date or duration_days, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Look up') and resource ('weather forecast'), making the tool's purpose immediately clear. It does not, however, explicitly distinguish this tool from siblings like web-search or world-time, so it stops short of the highest clarity tier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives such as web-search, nor does it state any preconditions or exclusions. Usage is only implied by the phrase 'Look up weather forecast for location,' which is not enough for explicit routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
web-searchA
REQUIRED live-web search for current or externally verifiable information, including benchmark scores, specifications, prices, news, documentation, and comparisons. Return source URLs, snippets, and clean results.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query to execute | |
| max_results | No | Maximum number of results to return |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so the description carries the full behavioral burden. It discloses the return shape (source URLs, snippets, clean results), which is useful, but says nothing about read-only nature, rate limits, latency, or reliance on live external sources beyond the word 'live'. Adequate but thin for a no-annotation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with zero filler; the required-use trigger and the covered categories are front-loaded before the return-format note. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description compensates by describing the return (source URLs, snippets, results), and the input parameters are fully covered by the schema. The main gap is the absence of any reliability or freshness caveat around 'live' results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'query' and 'max_results' (default 10, max 25) fully documented in the schema. The description adds no syntax, format, or query-construction guidance beyond what the schema already provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('live-web search') and enumerates the information types it covers (benchmark scores, specifications, prices, news, documentation, comparisons), which implicitly separates it from the specialized siblings like image-search, finance, weather, and sports. It does not explicitly name those alternatives, but the general-purpose factual scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear trigger condition — use for 'current or externally verifiable information' — with 'REQUIRED' emphasizing the mandate. It stops short of naming an alternative or stating when-not to use it, but the freshness criteria is concrete enough to route most cases correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
world-timeB
Get current time for UTC offset (e.g. '+08:00' or '-05:00').
| Name | Required | Description | Default |
|---|---|---|---|
| utc_offset | Yes | UTC offset string (e.g. '+08:00' or '-05:00') |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It implies a non-destructive read of 'current time', but discloses nothing about the return format, whether a date is included, or any locality/timezone semantics. Only the most obvious trait is conveyed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the action and immediately followed by the required input format. No filler, no restated title, nothing that fails to earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, schema-complete tool with no output schema, the description is adequate but leaves the response shape undefined (time only? offset echo? date?). It does usefully clarify that the input is an offset rather than a place name, which is the main ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single parameter is fully documented there. The description repeats the same '+08:00' / '-05:00' example verbatim, adding no syntax, validation, or edge-case detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get current time') plus the exact input shape (UTC offset), so the agent knows precisely what the tool yields. It does not need sibling differentiation since no sibling in the list (weather, finance, sports, web-search) overlaps with time lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the offset example suggests the tool is for looking up the time at a given offset rather than at a named city or timezone. There is no explicit when-to-use guidance, no statement of when this is preferable to alternatives, and no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
11 tool updates
v1.0.0- First observed
click-link - First observed
fetch - First observed
finance - First observed
find-in-page - First observed
image-search - First observed
open-page - First observed
screenshot-pdf - First observed
sports - First observed
weather - First observed
web-search - First observed
world-time
TDQS
Scored across 11 tools
The lookup tools (finance, weather, sports, world-time) are clearly distinct from each other and from the search tools. The browsing cluster (web-search, fetch, open-page, click-link, find-in-page, screenshot-pdf) is mostly separable by action, but fetch vs open-page overlap in that both take a URL and return page content, which could cause misselection.
Verbs use a hyphenated verb_noun pattern (web-search, open-page, click-link, find-in-page, image-search), but there are deviations: bare 'fetch', the hyphen-only 'screenshot-pdf', and noun-only tools (finance, weather, sports, world-time). Readable but not a single predictable convention.
11 tools is within a reasonable range for a combined web-search and lookup server. The six browsing tools feel somewhat heavy for page interaction, but each covers a distinct capability and nothing is clearly redundant.
Core search and browsing coverage is solid: search, content fetch, open, link navigation, in-page find, screenshot, and image search. The domain lookups round out common queries; there are minor gaps (e.g. no news/translation tools) but these are workable via web-search.
Maintenance
Related MCP Connectors
Live AI-native web search with citations. One tool for every MCP client. Flat per-request pricing.
Stealth web browser for agents: search, fetch, click, download and type in persistent MCP sessions.
Scrape, crawl and search the web for AI agents via MCP.
One MCP for the Web. Easily search, crawl, navigate, and extract websites without getting blocked.…
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides comprehensive search capabilities including web search, content extraction, news search, academic search, and AI-powered multi-source research. Enables natural language access to web content and research through a production-ready MCP server.-
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to perform web searches and fetch web pages over HTTP, using Exa and Parallel AI as search providers without requiring API keys.MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to conduct search-first web research through source discovery, page retrieval by ID, and direct URL reading.2MIT
- FlicenseAqualityBmaintenanceEnables web search and anonymous public-page retrieval through MCP, with provider-neutral selection, bounded plain-text results, and built-in auditing.2-