git:20260830.c2263a9 to git:20260830.762414e

---

name: mathodology-evidence-search

description: Use when an award run needs external evidence — literature, datasets, benchmarks, domain constants, prior-art checks, or citation verification — with combined built-in WebSearch and search MCP discovery, source reconciliation, document reading, citation confirmation, token budgets, and reproducibility rules.

---

# Mathodology Evidence Search

Award submissions are scored on traceability: every constant, benchmark, dataset,

and domain claim must resolve to a source, a derivation, or an explicitly stated

assumption. This skill defines how Mathodology agents acquire and verify that

external evidence, so search work is repeatable instead of improvised per run.

## Tool Stack

The `search` MCP server ([free-search-mcp](https://github.com/sweetcornna/free-search-mcp))

complements built-in `WebSearch` as a peer discovery channel. Its tools appear as `mcp__search__<tool>`:

| Tool | Use it for |

|---|---|

| `search(query, ...filters)` | Source discovery. Multi-engine, RRF-merged, deduplicated link list. |

| `research(question, depth, ...filters)` | One open question you cannot yet phrase as a URL hunt: search + fetch top N + Markdown brief in one call. |

| `fetch(url, render?)` | Read one page as Markdown, or describe a non-text resource. |

| `fetch_batch(urls)` | Read up to 20 shortlisted URLs concurrently. |

| `read_doc(source, start?, length?)` | Read PDF / DOCX / XLSX / PPTX / EPUB / CSV / HTML with pagination — the correct tool for a paper PDF or a data file, not `fetch`. |

| `compare(question, urls=[2..5])` | Reconcile a constant or definition that two to five sources state differently. |

| `extract_structured(url)` | Pull JSON-LD / OpenGraph / microdata — DOI, authors, journal, volume, pages, date. The mechanical path to citation specifics. |

| `paper_graph(identifier, limit?)` | The mechanical prior-art and retraction check for one paper by DOI, OpenAlex ID, or exact title — its references, its citing works ordered by how heavily the field cited those in turn, and any Crossref retraction, correction, or expression of concern. A retracted citation is a submission risk this tool finds, not one WebSearch reliably surfaces. |

| `cache_search(query, limit?)` | Full-text search over pages already fetched in this run. Cheap; use before re-fetching. |

| `engines()` | Check which engines are available before blaming a query for thin results. |

| `download(url)` | Keep an actual file — a contest data attachment, a dataset archive, a PDF the coder must read. Staging only: see *Reproducibility Boundary*. |

A normal project installation exposes the full MCP list, including `download`.

Filters on `search` / `research`: `freshness` (`day`/`week`/`month`/`year`),

`include_domains`, `exclude_domains`, `category`, `include_text`, `exclude_text`.

## Availability And Explicit Degradation

Contract assertions:

- `dual-source-default: WebSearch + mcp__search__search`

- `single-source-mode: explicit degradation`

- `search_backend: combined`

A clone of this repository registers the server at project scope through its `.mcp.json`,

so the tools are normally present after the user approves the server once. They can still

be missing — a skills-only install into another project, a client that does not read

project MCP config, or a machine without `uv`. Inspect available tools once at the start of an evidence task and record one mode:

- `combined` — the default. Use both `WebSearch` and `mcp__search__search` for discovery.

- `search-mcp` — degraded mode when built-in `WebSearch` is unavailable.

- `builtin` — degraded mode when MCP discovery is unavailable.

- `none` — neither discovery channel is available; set the handoff status to `blocked`.

A `combined` run logs at least one query from each backend. Either single-source mode

requires a reason and its coverage loss under `missing_evidence`. Never silently

degrade or convert unavailable search into evidence of absence.

Treat MCP capabilities individually. If search works but `download` is absent,

Registering it elsewhere with downloads enabled (no API key):

```bash

# Claude Code

claude mcp add --transport stdio --env "SEARCH_MCP_DOWNLOAD_DIR=$HOME/.cache/search-mcp/downloads" search -- uvx free-search-mcp

# Codex

codex mcp add --env "SEARCH_MCP_DOWNLOAD_DIR=$HOME/.cache/search-mcp/downloads" search -- uvx free-search-mcp

```

## Routing Rules

`category` is a two-level tree and routes the query to sources a general web engine

cannot index. Passing `category` also changes the order of results, not only which

engines run, because an engine that natively indexes the requested category counts

double in the rank fusion. Pass it instead of hand-listing engines. The tool schema's

enum lists every group and sub-group, so an agent discovers the tree from the schema

alone, without a second call.

A bare group is capped (three engines by default) and round-robins across its

sub-groups; a dotted sub-group narrows to that one corpus:

- `paper` — literature and prior-art queries. `paper.index` (OpenAlex, Crossref,

Semantic Scholar behind an optional key), `paper.preprint` (arXiv, Europe PMC),

`paper.biomed` (Europe PMC, PubMed), `paper.cs` (DBLP), `paper.openaccess` (Europe

PMC, DOAJ), `paper.trial` (ClinicalTrials.gov), `paper.math` (zbMATH Open).

Hostname-filtering general web results is not a literature search.

- `dataset` — `dataset.repository` (Zenodo, Dryad, Harvard Dataverse, figshare),

`dataset.ml` (Hugging Face Hub), `dataset.gov` (data.europa.eu). **Exclusive**:

replaces the default pool instead of augmenting it, so no general web engine is

there to catch a miss — with five sources behind it now, one dead source is far

less likely to be mistaken for the whole category; still check `engines()` and

route an empty result to `missing_evidence`, never to an absence claim.

- `news` — Google News; `news.world` narrows to GDELT for non-English and

cross-border event coverage.

- `finance` — `finance.filings` (SEC EDGAR, cninfo A-share/HK announcements),

`finance.market` (Yahoo Finance), `finance.macro` (World Bank, IMF).

- `github` — repository metadata for reference implementations.

- `forum` — Stack Exchange and Hacker News, for accepted-answer signal on a method.

- `image` — Openverse, Wikimedia Commons; results are direct file URLs. **Exclusive**:

replaces the default pool instead of augmenting it.

Naming `engines=[...]` explicitly disables this routing — do that only to reach a

specific opt-in engine (for example `google`, `wikipedia`, or the Chinese-language

engines for a CUMCM/华数杯 domain term).

## Search Protocol

Per evidence item in the source ledger:

1. Check the ledger and `cache_search` before fetching material already read.

2. In `combined` mode, run complementary queries through both built-in `WebSearch`

and `mcp__search__search`; use the narrowest MCP `category` and filters. Do not

wait for one channel to fail before using the other.

3. Log every query in `queries_run` with `backend: builtin` or `backend: search-mcp`.

4. Merge results before reading. Deduplicate by canonical DOI when available;

otherwise canonicalize the URL by removing fragments and tracking parameters.

Preserve every contributing channel in each accepted source's `discovered_by` list.

5. Shortlist by title, host, date, and claim fit — not rank alone. Prefer primary

sources (publisher, standards body, statistical agency) over aggregators and blogs.

6. Choose one reader by resource type: `read_doc` for PDFs and data/office files;

MCP `fetch`/`fetch_batch` or built-in `WebFetch` for pages. Discovery by both

channels does not require duplicate fetches.

7. Use `compare` when sources disagree on a value you will print or model. Record

the disagreement, chosen value, and reason.

8. Record canonical DOI/URL, original URL, `discovered_by`, date, access date,

credibility note, and extracted quantity for every accepted source.

Thin or empty results are a diagnosis, not an answer. Check `engines()` and the

server's `rescued_via` note: a gated or CAPTCHA-walled engine looks identical to

"no such source exists" if you do not look. Report a blocked search as a gap in

`missing_evidence`; never convert it into an implicit claim that no evidence exists.

## Citation Verification Protocol

A citation is verified only when the URL resolves to the *primary* work being

cited — not a "cited-by" entry, not a neighbouring article in the same issue, not

a preprint of a paper you cite by its journal pagination.

1. Read the landing page or document once with the type-appropriate reader:

`read_doc`, MCP `fetch`, or built-in `WebFetch`; confirm the title and authors.

2. When available, use `extract_structured` on the landing page to read DOI,

journal, volume, issue, pages, and publication date from publisher metadata

rather than from a search snippet; otherwise verify them on the publisher page.

3. Anything you cannot confirm down to the specifics the paper will print goes on

`citations_to_verify` with `verified: false`. Do not print a page or volume

number that no tool call confirmed.

4. Run `paper_graph` on each citation load-bearing to a claim, keyed by its

confirmed DOI, OpenAlex ID, or exact title. Note any Crossref retraction,

correction, or expression of concern against the citation record — a retracted

source is a submission risk, not a stylistic issue, and this is the mechanical

way to catch one before the paper ships.

5. `cache_search` makes this auditable: `mathodology-critic` can re-read the exact

page the researcher saw, without re-fetching, when closing the citation gate.

## Reproducibility Boundary

Interactive search is not a reproducible pipeline stage.

- Evidence acquisition (this skill) produces a ledger of URLs, quotes, and values.

- Any number that enters the model or the paper must be re-derivable from a file

under `work/<run-id>/` or a scripted download that `mathodology-coder` commits,

not from an unrepeatable tool call.

- `download` writes to a **staging** directory that purges itself after 24 hours. It is

the right tool when a real file is needed — contest attachments, dataset archives,

a PDF the coder parses — and the wrong one for reading content, where `read_doc`

and `fetch` touch no filesystem at all.

- Anything downloaded must be copied into `work/<run-id>/data/` in the same turn, and

the ledger records its URL plus the SHA-256 the tool prints. A file left only in the

staging directory is gone by the next day and the packager cannot account for it.

- The URL and hash are what make the download reproducible: a committed script can

re-acquire the file and verify it is the same bytes the results were computed from.

- Respect licensing. Note license or usage constraints on any dataset in the ledger;

a dataset that cannot be redistributed must not end up inside the submission package.

## Token Discipline

- Keep `format="markdown"` (default). Pass `format="json"` only when a script

parses the output.

- `research(depth=N)` fetches N full documents — use it for a genuinely open

question, not to read one URL you already have.

- Read the part of a long PDF you need with `read_doc(start=..., length=...)`

instead of pulling the whole document into context.

- Cap breadth per claim: three to five accepted sources beat twenty skimmed ones,

and the ledger stays reviewable.

## Who Uses This

- `mathodology-evidence-researcher` — primary owner, Phase 1 and every later

evidence request.

- `mathodology-critic` — verification only against the researcher's ledger with

its existing readers, metadata, cache, and retraction-check tools; it does not

start a new discovery pass. `paper_graph` is scoped to the retraction/correction

field on citations already in the ledger, keyed by their confirmed identifier —

not to mining its references or citing-works lists for prior art the researcher

has not already found, which stays discovery and stays out of scope here.

- `mathodology-award-judge` — **never**. Judge seats score the rendered PDF and the

artifact list blind; external lookups break the blind protocol in

`.claude/skills/mathodology-award-gates/SKILL.md`.

## Handoff Keys

The canonical role-specific contract lives in

`.claude/skills/mathodology-award-gates/SKILL.md`. Evidence work carries:

```yaml

search_backend: combined # combined | search-mcp | builtin | none

queries_run: [] # each includes {query, backend, category, engines_note, accepted, rejected}; backend: search-mcp | builtin

citations_to_verify: [] # each: {id, claim, source, url, verified}

missing_evidence: [] # blocked/gated/paywalled gaps and every backend/configuration degradation reason

```

Accepted sources are deduplicated by canonical DOI/URL and carry `discovered_by`.

`combined` requires both query backends; either single-source mode requires a

`missing_evidence` degradation reason; `none` requires a blocked handoff.