Tool reference

Every tool's input is validated by a Zod schema. Defaults match the "safe boring choice" — spec defaults to "262", edition defaults to "latest", limits are generous but bounded, and toggleable expensive options (like search_steps and include_cross_spec) are off by default.

All spec-reading tools accept spec ("262" | "402") and edition arguments. See editions.md for the value set and how aliases resolve per spec.

Each tool section below carries:

• What it answers — co-located example calls, each tagged with the natural-language question it resolves.
• Input — every field from the Zod schema with its type, default, and inline help text.
• Output — the handler's declared return type, expanded into a field table when it names a locally-defined interface.

spec.about

Return self-description of this MCP server: package name + version, per-snapshot pin metadata (sha, fetched_at, biblio_commit, clause_count) for every supported (spec, edition), plus test262 + proposals index headers when present. Lets callers verify freshness and reproducibility without loading the parses themselves.

What it answers

• How fresh is this server's data, and what version is it? — {}
  • Cheap call — no clause trees loaded. Each snapshot reports its upstream SHA + fetched_at so downstream callers can pin reproducibility.

Input

No parameters.

Output

Returns AboutResult.

AboutResult

Field	Type	Description
server	{ name: string; version: string; }	Package name + version of this MCP server.
generated_at	string	When this spec.about response was assembled.
snapshots	SnapshotInfo[]	One entry per supported (spec, edition) pair, regardless of whether the snapshot is present locally.
test262_index	{ test262_sha: string; generated_at: string; test_count: number; bytes_on_disk: number; } (optional)	test262 index metadata, when present.
proposals_index	{ proposals_sha: string; generated_at: string; proposal_count: number; bytes_on_disk: number; } (optional)	tc39/proposals index metadata, when present.

spec.snapshots

List every (spec, edition, sha, fetched_at) snapshot this server has parsed. Use to discover what historical SHAs you can query via at: "<sha>", or to verify reproducibility across server versions. Optional spec / edition filters.

What it answers

• List every (spec, edition) the server has parsed — {}
• Just the ECMA-402 snapshots — {"spec":"402"}

Input

Field	Type	Default	Description
spec	"262" | "402" (optional)	—	Filter to one spec. Omit for both.
edition	string (optional)	—	Filter to one edition (concrete name like 'main' or 'es2025'). Omit for all.

Output

Returns SnapshotsResult.

SnapshotsResult — Output of spec.snapshots: every parsed (spec, edition, sha, fetched_at) snapshot the server has available, plus the filters the call narrowed to.

Field	Type	Description
spec_filter	Spec (optional)	Echo of the spec argument, if one was supplied.
edition_filter	string (optional)	Echo of the edition argument, if one was supplied.
snapshots	SnapshotRow[]	Matching snapshot rows. On the stdio server this is whatever the installed package version baked in; on the Worker this can include historical SHA-pinned copies.

clause.get

Fetch a parsed TC39 clause as structured JSON: metadata, signature, algorithm steps, notes, cross-refs. spec selects '262' (default) or '402'. edition defaults to latest (262: current stable release; 402: main, since 402 has no annual release tags).

What it answers

• What are the steps of ToNumber? — {"id":"sec-tonumber"}
• What does the ECMA-402 NumberFormat constructor look like? — {"id":"sec-intl.numberformat","spec":"402"}

Input

Field	Type	Default	Description
id	string	—	Spec clause id, e.g. 'sec-tonumber' (262) or 'sec-intl.numberformat' (402).
spec	"262" | "402"	"262"	Which TC39 spec to read: '262' (core language, default) or '402' (Internationalization API).
edition	EDITION_VALUES	"latest"	Edition within the chosen spec. ECMA-262: es2016 … es2025, main. ECMA-402: main, es2025-candidate. Aliases: latest, draft, next.

Output

Returns Clause | null.

clause.list

List parsed spec clauses with optional filters (kind, section prefix, has_algorithm). Returns lightweight rows {id, aoid, title, number, kind, algorithms}; follow up with clause.get for detail. spec selects '262' or '402'.

What it answers

• Every SDO in ECMA-262 — {"kind":"sdo"}
• Built-in functions under §22.2 (RegExp) — {"kind":"built-in function","section":"22.2"}

Input

Field	Type	Default	Description
spec	"262" | "402"	"262"	Which TC39 spec to read: '262' (core language, default) or '402' (Internationalization API).
edition	EDITION_VALUES	"latest"	Edition within the chosen spec. ECMA-262: es2016 … es2025, main. ECMA-402: main, es2025-candidate. Aliases: latest, draft, next.
kind	string (optional)	—	Filter by clause kind (e.g. 'op', 'sdo', 'built-in function', 'concrete method').
section	string (optional)	—	Filter to clauses whose section number starts with this prefix, e.g. '22.2' for RegExp or '15' for the Locale-aware operations in ECMA-402.
has_algorithm	boolean (optional)	—	If true, return only clauses with at least one <emu-alg>.
limit	number (int, 1–2500)	200	Max clauses returned. The full spec has ~3000 clauses; the default is a safe slice.

Output

Returns ClauseListHit[].

ClauseListHit — Lightweight metadata row for one clause, returned by clause.list. Use the id to follow up with clause.get for the full structured clause (signature, steps, notes, cross-refs).

Field	Type	Description
id	string	Spec clause id, e.g. sec-tonumber.
aoid	string | null	Abstract Operation ID — the spec's identifier for invocable operations (e.g. ToNumber). null for clauses that aren't abstract operations (built-ins, methods, prose-only clauses).
title	string	<h1> text of the clause, including any signature line.
number	string	Section number, e.g. 7.1.4 or B.3.1 (Annex B).
kind	string	Clause kind: op, sdo, built-in function, concrete method, internal method, term, clause (generic), or unknown.
algorithms	number	Number of <emu-alg> blocks under this clause. 0 for prose-only clauses; >1 for SDOs which define one algorithm per production.

clause.outline

Return the section tree (table of contents) for a parsed (spec, edition). depth caps tree depth (1 = top-level only). under anchors at a specific clause id so you get just its descendants. Each node carries { id, number, title, kind, children }.

What it answers

• Top-level section tree of ECMA-262 — {"depth":1}
• Everything under §22.2 (RegExp) — {"under":"sec-regexp-regular-expression-objects"}

Input

Field	Type	Default	Description
spec	"262" | "402"	"262"	Which TC39 spec to read: '262' (core language, default) or '402' (Internationalization API).
edition	EDITION_VALUES	"latest"	Edition within the chosen spec. ECMA-262: es2016 … es2025, main. ECMA-402: main, es2025-candidate. Aliases: latest, draft, next.
depth	number (int, 1–10) (optional)	—	Max tree depth to return. 1 = top-level only; 2 = first two levels; omitted = full tree.
under	string (optional)	—	Optional clause id. If set, return only descendants of this clause.

Output

Returns OutlineResult.

OutlineResult — Output of clause.outline: the section tree for one (spec, edition).

Field	Type	Description
spec	Spec	Which TC39 spec the outline is from: 262 or 402.
node_count	number	Number of nodes in the returned tree (after depth / under filters are applied).
roots	OutlineNode[]	Top-level nodes of the returned tree. If under was set, these are that anchor's direct children rather than the spec roots.

spec.search

Search the parsed spec by clause id / aoid / title (and step text when search_steps is true). Returns lightweight hits ranked by match quality — the entry point when you don't know the exact clause id. spec selects '262' or '402'. Follow up with clause.get.

What it answers

• Find the clause that defines Canonicalize — {"query":"Canonicalize"}
  • Ranks aoid-exact matches first; useful when you have an op name from an error or a prose mention.
• Where is sloppy-mode unbound this resolved? — {"query":"this","search_steps":true}
  • search_steps: true also scans algorithm step text. Slower + noisier than the default but the only way to catch in-step mentions.

Input

Field	Type	Default	Description
query	string	—	Search text. Matched against clause id, aoid, and title (and step text when search_steps is true).
spec	"262" | "402"	"262"	Which TC39 spec to read: '262' (core language, default) or '402' (Internationalization API).
edition	EDITION_VALUES	"latest"	Edition within the chosen spec. ECMA-262: es2016 … es2025, main. ECMA-402: main, es2025-candidate. Aliases: latest, draft, next.
limit	number (int, 1–100)	20	Max ranked hits returned.
search_steps	boolean	false	Also match against algorithm step text. Slower + noisier; off by default.

Output

Returns SpecSearchHit[].

SpecSearchHit — One ranked search hit from spec.search. Lightweight metadata — follow up with clause.get for the full structured clause.

Field	Type	Description
id	string	Spec clause id of the matching clause.
aoid	string | null	Abstract Operation ID of the matching clause, or null if it isn't an abstract operation.
title	string	<h1> text of the matching clause.
number	string	Section number, e.g. 7.1.4.
kind	string	Clause kind: op, sdo, built-in function, etc.
matched_on	"aoid-exact" | "aoid" | "title" | "id" | "steps"	Which field produced the highest-ranked match. Ordering (high → low): aoid-exact, aoid, title, id, steps.
score	number	Relevance score (0–100). Higher = stronger match.

spec.crossrefs

For a clause id, return its outgoing references (clauses it cites) and/or incoming references (clauses that cite it — the back-reference index the parse alone doesn't expose). Direction: 'in' | 'out' | 'both' (default). Set include_cross_spec: true to also resolve outgoing references from ECMA-262 → ECMA-402 (or vice versa).

What it answers

• Which clauses cite ToNumber? — {"id":"sec-tonumber","direction":"in"}
  • The reverse index is AOID-densified — bare AOID mentions in step text count, not just explicit <emu-xref> hrefs.
• Every 262 op that Intl.Collator's compare reaches — {"id":"sec-intl.collator.prototype.compare","spec":"402","direction":"out","include_cross_spec":true}
  • include_cross_spec is off by default because it loads both specs into memory. Turn it on when you want the full call graph across 262/402.

Input

Field	Type	Default	Description
id	string	—	Spec clause id, e.g. 'sec-tonumber' (262) or 'sec-intl.numberformat' (402).
spec	"262" | "402"	"262"	Which TC39 spec to read: '262' (core language, default) or '402' (Internationalization API).
edition	EDITION_VALUES	"latest"	Edition within the chosen spec. ECMA-262: es2016 … es2025, main. ECMA-402: main, es2025-candidate. Aliases: latest, draft, next.
direction	"in" | "out" | "both"	"both"	'in' = clauses that reference this one (back-refs); 'out' = clauses this one references; 'both' = both.
include_cross_spec	boolean	false	If true, outgoing references also include AOIDs that resolve to the other TC39 spec (262 ↔ 402). Useful for queries like 'every 262 op that calls into Intl'. Off by default because it requires loading both specs.
limit	number (int, 1–500)	100	Max hits returned in each direction (incoming and outgoing are limited independently).

Output

Returns CrossrefsResult.

spec.diff

Clause-level diff across any two editions of one spec. Defaults: from='latest', to='main' (working draft). Reports status (identical / modified / added / removed / missing-from-both) plus a field-level diff: title, signature, step count, per-step reworded indices, notes, crossrefs. spec selects '262' or '402'.

What it answers

• How did ToNumber change from es2024 to the working draft? — {"id":"sec-tonumber","from":"es2024","to":"main"}
  • Returns status ('identical' / 'modified' / etc.) plus a per-field diff. Pair with spec.history (Cookbook recipe 2) for a temporal walk.

Input

Field	Type	Default	Description
id	string	—	Spec clause id.
spec	"262" | "402"	"262"	Which TC39 spec to read: '262' (core language, default) or '402' (Internationalization API).
from	EDITION_VALUES	"latest"	The 'before' edition. Defaults to the latest stable release.
to	EDITION_VALUES	"main"	The 'after' edition. Defaults to the working draft (main).

Output

Returns SpecDiffResult.

SpecDiffResult — Output of spec.diff: clause-level comparison between two editions of the same TC39 spec.

Field	Type	Description
id	string	Spec clause id that was diffed.
from	ConcreteEdition	Concrete edition the from argument resolved to (e.g. es2024).
to	ConcreteEdition	Concrete edition the to argument resolved to (e.g. main).
same	boolean	true iff the clause is byte-identical (after the structural pass) across the two editions.
status	| "identical" | "modified" | "added" | "removed" | "missing-from-both"	High-level verdict for this clause across the two editions. identical — no structural changes detected. modified — present in both, but differs in one or more fields. added — exists in to, missing from from. removed — exists in from, missing from to. missing-from-both — not found in either edition.
from_summary	ClauseSummary (optional)	Brief snapshot of the clause in the from edition (title, signature, step/note counts). Absent when status is added.
to_summary	ClauseSummary (optional)	Brief snapshot of the clause in the to edition. Absent when status is removed.
diffs	{ /** Which clause field changed. */ field: "title" | "signatureRaw" | "steps" | "notes" | "crossrefs"; /** Value (or count) in the fromedition. */ before: string | number; /** Value (or count) in theto edition. */ after: string | number; /** Optional human-readable note about the change (e.g. step * rewording summary). */ detail?: string; }[] (optional)	Field-by-field difference list. Each entry names the field that changed, its before/after values (or counts for collection fields), and an optional human-readable detail string.

spec.history

Recent commits in the vendored spec checkout that touched a clause's id="..." token. Uses git pickaxe (-S) so it catches clause creation, deletion, and edits to the opening tag reliably; interior-text-only edits won't show. Returns SHA, date, author, subject per commit. spec selects '262' or '402'.

What it answers

• Recent edits to ToNumber's clause tag — {"id":"sec-tonumber"}

Input

Field	Type	Default	Description
id	string	—	Spec clause id.
spec	"262" | "402"	"262"	Which TC39 spec to read: '262' (core language, default) or '402' (Internationalization API).
edition	EDITION_VALUES	"latest"	Edition within the chosen spec. ECMA-262: es2016 … es2025, main. ECMA-402: main, es2025-candidate. Aliases: latest, draft, next.
limit	number (int, 1–100)	20	Max commits returned from the vendored spec checkout's git log.

Output

Returns SpecHistoryResult.

SpecHistoryResult — Output of spec.history: commits in the vendored spec checkout that touched the opening tag of a given clause id.

Field	Type	Description
id	string	Clause id that was queried.
spec	Spec	Which TC39 spec was queried.
edition	ConcreteEdition	Concrete edition the edition arg resolved to.
vendor_present	boolean	false when no vendored checkout exists for this (spec, edition); commits will be empty and hint may explain how to fetch.
shallow	boolean	true when the vendored checkout is a shallow clone; the commit list may be truncated. hint suggests git fetch --unshallow.
commits	SpecHistoryCommit[]	Commits returned, newest first, capped at limit.
hint	string (optional)	Human-readable note (e.g. setup or shallow-clone hint).

spec.symbol_resolve

Resolve spec notation like [[Prototype]] (internal slot), %Object.prototype% (well-known intrinsic), or ~number~ (sigil enum) to the clauses that mention or define it. Hits ranked by occurrence count + section-prefix bumps for the canonical definition location. spec selects '262' or '402'.

What it answers

• What does [[Prototype]] mean? — {"notation":"[[Prototype]]"}
  • Classified as internal-slot. Ranking bumps clauses in §6 (type domain) and §10 (ordinary + exotic objects).
• Where is %Object.prototype% defined? — {"notation":"%Object.prototype%"}
  • Classified as intrinsic. Cross-check with spec.tables({ id: "table-well-known-intrinsic-objects" }) for the authoritative WKI table.
• What is the ~enumerate~ hint? — {"notation":"~enumerate~"}
  • Classified as sigil-enum. Useful for the Hint enums passed to ToPrimitive and friends.

Input

Field	Type	Default	Description
notation	string	—	Spec notation like [[Prototype]] (internal slot), %Object.prototype% (well-known intrinsic), or ~number~ (sigil enum).
spec	"262" | "402"	"262"	Which TC39 spec to read: '262' (core language, default) or '402' (Internationalization API).
edition	EDITION_VALUES	"latest"	Edition within the chosen spec. ECMA-262: es2016 … es2025, main. ECMA-402: main, es2025-candidate. Aliases: latest, draft, next.
limit	number (int, 1–50)	10	Max candidate clauses returned, ranked by relevance score.

Output

Returns SymbolResolveResult.

SymbolResolveResult — Output of spec.symbol_resolve: candidate clauses likely to define or describe a spec notation like [[Prototype]].

Field	Type	Description
notation	string	The original notation as passed in.
kind	SymbolKind	How the notation was classified. unrecognized triggers a literal search rather than a sigil-aware one.
name	string	Bare name with sigils stripped (e.g. Prototype for [[Prototype]]).
hits	SymbolHit[]	Candidate clauses, ranked, capped at limit.

spec.sdo_index

Index Syntax-Directed Operations by the grammar production they handle. SDOs are abstract operations (Evaluation, BoundNames, etc.) with one <emu-alg> per production. Default by='production' returns { [production]: [{ sdo, id, title }] }; by='sdo' returns { [sdo title]: [productions] }. filter substring-narrows keys; spec selects '262' or '402'.

What it answers

• Which SDOs implement BindingIdentifier? — {"by":"production","filter":"BindingIdentifier"}
• What productions does Evaluation handle? — {"by":"sdo","filter":"Evaluation"}

Input

Field	Type	Default	Description
spec	"262" | "402"	"262"	Which TC39 spec to read: '262' (core language, default) or '402' (Internationalization API).
edition	EDITION_VALUES	"latest"	Edition within the chosen spec. ECMA-262: es2016 … es2025, main. ECMA-402: main, es2025-candidate. Aliases: latest, draft, next.
by	"production" | "sdo"	"production"	Index direction. 'production' (default) groups SDO definitions by the production they handle. 'sdo' groups productions by which SDO defines them.
filter	string (optional)	—	Optional filter: substring match on the production text or SDO title. Returns only entries whose key contains this string (case-insensitive).
limit	number (int, 1–500)	50	Cap the number of groups returned. Each group can still hold many entries.

Output

Returns SdoIndexResult.

SdoIndexResult — Output of spec.sdo_index: the SDO ↔ production index either grouped by production (the default) or by SDO title.

Field	Type	Description
spec	Spec	Which TC39 spec the index was built from.
by	"production" | "sdo"	Which direction the index runs. production keys productions to the SDOs implementing them; sdo keys SDO titles to the productions they cover.
pair_count	number	Total number of (production, sdo) pairs in the source. Useful for context when groups was truncated by limit.
group_count	number	Number of unique groups (productions when by=production, SDO titles when by=sdo).
groups	Record<string, SdoEntry[]>	The actual index. Keys are productions or SDO titles depending on by. Values are the entries grouped under that key.

spec.global_search

Run spec.search across both ECMA-262 and ECMA-402 in one call and interleave results by score. Each hit is tagged with the spec it came from. Useful when you don't know which spec defines the symbol (e.g. Canonicalize is 262, CanonicalizeLocaleList is 402).

What it answers

• Where is Canonicalize defined across both specs? — {"query":"Canonicalize"}

Input

Field	Type	Default	Description
query	string	—	Search text. Matched against clause id, aoid, and title across both specs (and step text when search_steps is true).
search_steps	boolean	false	Also match against algorithm step text. Slower + noisier; off by default.
limit	number (int, 1–100)	20	Total hits across both specs combined.

Output

Returns GlobalSearchHit[].

GlobalSearchHit — One ranked search hit, tagged with the spec it came from. Returned by spec.global_search as an interleaved list across both 262 and 402, sorted by score. Same shape as SpecSearchHit plus spec.

Field	Type	Description
spec	Spec	Which TC39 spec contains the matching clause: 262 or 402.

spec.well_known_intrinsics

Enumerate the well-known intrinsics (%X% notations) used in the spec, with each one's probable defining clause (chosen by a title-substring heuristic — see matched_on per hit). For the canonical 262 well-known intrinsics table, read clause.get { id: 'sec-well-known-intrinsic-objects' } directly.

What it answers

• Every well-known intrinsic in ECMA-262 — {}
• Well-known intrinsics named like Array — {"filter":"array"}

Input

Field	Type	Default	Description
spec	"262" | "402"	"262"	Which TC39 spec to read: '262' (core language, default) or '402' (Internationalization API).
edition	EDITION_VALUES	"latest"	Edition within the chosen spec. ECMA-262: es2016 … es2025, main. ECMA-402: main, es2025-candidate. Aliases: latest, draft, next.
filter	string (optional)	—	Case-insensitive substring filter on the intrinsic name (bare, e.g. 'object.prototype').
limit	number (int, 1–500)	100	Max well-known intrinsics returned.

Output

Returns IntrinsicsResult.

IntrinsicsResult — Output of spec.well_known_intrinsics: every well-known intrinsic detected in the spec, with the clause that probably defines it.

Field	Type	Description
spec	Spec	Which TC39 spec was scanned.
source	"table" | "heuristic"	Which resolution path produced these hits. table uses the authoritative §6.1.7.4 WKI table; heuristic falls back to a scan of clause titles + step text.
hint	string	Human-readable note describing how the hits were produced (e.g. table missing, fallback scan ran, etc.).
hits	IntrinsicHit[]	Matched intrinsics, capped at limit.

spec.tables

List or fetch parsed <emu-table> content. Pass id to get one table with full columns + rows; omit id to list tables (lightweight summaries) optionally filtered by caption/id substring. Authoritative source for the well-known intrinsics table (id='table-well-known-intrinsic-objects'), well-known symbols, completion record fields, etc. spec selects '262' or '402'.

What it answers

• The authoritative well-known intrinsics table — {"id":"table-well-known-intrinsic-objects"}
• List every captured <emu-table> in ECMA-262 — {}

Input

Field	Type	Default	Description
id	string (optional)	—	If set, return exactly this table (full columns + rows). If omitted, list tables (lightweight rows).
filter	string (optional)	—	Case-insensitive substring filter on the caption or id (list mode only).
spec	"262" | "402"	"262"	Which TC39 spec to read: '262' (core language, default) or '402' (Internationalization API).
edition	EDITION_VALUES	"latest"	Edition within the chosen spec. ECMA-262: es2016 … es2025, main. ECMA-402: main, es2025-candidate. Aliases: latest, draft, next.
limit	number (int, 1–500)	50	Max table summaries returned in list mode (ignored when 'id' is set).

Output

Returns SpecTablesResult.

spec.grammar

Query standalone <emu-grammar> productions from the spec's lexical / syntactic grammar (§11-15 in 262). Three modes: { nonterminal: 'X' } returns every production for X; { contains: 'Y' } returns productions whose RHS or non-terminal name contains Y; neither returns a list of all non-terminals with their production counts. Set include_sdo:true to also surface SDO-attached grammar headers.

What it answers

• Every standalone production for BindingIdentifier — {"nonterminal":"BindingIdentifier"}
• Productions mentioning yield — {"contains":"yield"}

Input

Field	Type	Default	Description
nonterminal	string (optional)	—	Filter to productions defining this non-terminal (exact match). Example: 'BindingIdentifier'.
contains	string (optional)	—	Filter to productions whose RHS lines or non-terminal name contain this substring (case-insensitive).
include_sdo	boolean	false	If true, also include productions captured as SDO algorithm headers. Off by default — most callers want the standalone lexical/syntactic grammar definitions.
spec	"262" | "402"	"262"	Which TC39 spec to read: '262' (core language, default) or '402' (Internationalization API).
edition	EDITION_VALUES	"latest"	Edition within the chosen spec. ECMA-262: es2016 … es2025, main. ECMA-402: main, es2025-candidate. Aliases: latest, draft, next.
limit	number (int, 1–500)	100	Max productions (or non-terminal groups in list mode) returned.

Output

Returns SpecGrammarResult.

test262.search

Search tc39/test262 for tests matching a free-text query and/or an esid (clause id, prefix-matched). test262 covers both ECMA-262 and ECMA-402. Served entirely from a local index (build/test262-index.json); if the index hasn't been built the result is empty + a hint explaining the one-time setup. No auth, no network, no subprocess.

What it answers

• Tests anchored to sec-tonumber — {"esid":"sec-tonumber"}
  • esid is prefix-matched: this also catches sec-tonumber-applied-to-the-string-type and other nested ids without listing them.
• Tests mentioning for-await-of — {"query":"for-await-of"}
  • query matches case-insensitively across description + path. Pair it with esid to AND-narrow.

Input

Field	Type	Default	Description
query	string (optional)	—	Free-text query. Matched case-insensitively as whitespace-separated tokens (AND) across each test's description + path. Either query or esid (or both) must be supplied.
esid	string (optional)	—	Filter to tests whose front-matter esid: starts with this prefix (case-insensitive). Prefix match catches the common case where test262 uses a more specific esid than the spec section id — e.g. esid: 'sec-tonumber' matches both sec-tonumber and sec-tonumber-applied-to-the-string-type.
limit	number (int, 1–100)	20	Max ranked hits returned from the test262 index.

Output

Returns Test262SearchResult.

Test262SearchResult — Output of test262.search: ranked hits from the local test262 index, plus the index SHA for reproducibility.

Field	Type	Description
query	string (optional)	Echo of the query argument (when present).
esid	string (optional)	Echo of the esid argument (when present).
source	"index" | "none"	Which backend served the query. - "index" → results from build/test262-index.json (always). - "none" → no index built; hits empty; hint explains setup.
index_sha	string (optional)	SHA of the vendored test262 checkout that produced this index. Absent when source: "none".
hits	Test262Hit[]	Ranked hits, capped at limit.
hint	string (optional)	Human-readable setup hint, set only when source: "none".

test262.get

Fetch one test's source + parsed front-matter by path within the vendored tc39/test262 checkout. Pairs with test262.search — the paths it returns plug in here directly. Returns { source, front_matter, test262_sha, url } or { hint } if the path can't be resolved.

What it answers

• Read one specific test262 file — {"path":"test/built-ins/Number/prototype/toString/S15.7.4.2_A1_T01.js"}

Input

Field	Type	Default	Description
path	string	—	Path within the test262 checkout, relative to the repo root. Example: 'test/built-ins/Number/prototype/toString/S15.7.4.2_A1_T01.js'. The values returned by test262.search go here directly.

Output

Returns Test262GetResult.

Test262GetResult — Output of test262.get: one test262 file's contents plus its structured front-matter, served from the vendored checkout.

Field	Type	Description
path	string	Echo of the requested path, relative to the test262 repo root.
test262_sha	string (optional)	SHA of the vendored test262 checkout that served this file.
url	string (optional)	Permanent URL to the file on GitHub at the vendored SHA.
source	string (optional)	Verbatim file source, including the front-matter comment block.
front_matter	Test262Frontmatter (optional)	Front-matter parsed into structured fields (esid, description, info, features, flags, includes, negative, plus any other keys under raw). Absent if the file has no front-matter block.
hint	string (optional)	Empty when found; populated when something went wrong.

proposal.list

List TC39 proposals from a static index built once from tc39/proposals. Filter by stage ('0'|'1'|'2'|'2.7'|'3'|'finished'|'inactive'|'active'), champion (substring), or contains (name/slug substring). Returns lightweight rows; follow up with proposal.get. Index-only: no auth, no network.

What it answers

• Proposals currently at Stage 3 — {"stage":"3"}
• Active proposals (stages 2 / 2.7 / 3) — {"stage":"active"}

Input

Field	Type	Default	Description
stage	string (optional)	—	Filter to one stage: '0', '1', '2', '2.7', '3', 'finished', 'inactive', or 'active' (anything in the active README — stages 2/2.7/3).
champion	string (optional)	—	Case-insensitive substring filter on the champion list.
contains	string (optional)	—	Case-insensitive substring filter applied to the proposal name + slug.
limit	number (int, 1–500)	100	Max proposals returned from the filtered set.

Output

Returns ProposalListResult.

ProposalListResult — Output of proposal.list: filtered slice of the TC39 proposals index, plus the index SHA so callers can pin reproducibility.

Field	Type	Description
source	"index" | "none"	index when the proposals index was loaded; none when it hasn't been built — see hint for the build command.
proposals_sha	string (optional)	SHA of the vendored tc39/proposals checkout that produced this index. Absent when source: "none".
total	number	Total proposals matching the filters before limit truncation.
proposals	ProposalEntry[]	Proposals matching the filters, capped at limit.
hint	string (optional)	Human-readable setup hint, set only when source: "none".

proposal.get

Fetch one TC39 proposal by slug (exact) or name (case-insensitive). Returns { slug, name, stage, authors, champions, url, test262_flag, source_file }. Slug is canonical — use what proposal.list returns directly.

What it answers

• Look up the Temporal proposal — {"name":"temporal"}

Input

Field	Type	Default	Description
name	string	—	Match against either the proposal's slug (preferred, exact-match) or its name (case-insensitive). Slug is the canonical id — use what proposal.list returns directly.

Output

Returns ProposalGetResult.

ProposalGetResult — Output of proposal.get: one proposal looked up by slug or name.

Field	Type	Description
source	"index" | "none"	index when the proposals index was loaded; none when it hasn't been built — see hint.
proposals_sha	string (optional)	SHA of the vendored tc39/proposals checkout that produced this index. Absent when source: "none".
proposal	ProposalEntry | null	The matched proposal, or null when nothing matched.
hint	string (optional)	Human-readable setup hint, set only when source: "none".

Error envelope

Tools that can fail return either { hits: [] } (search-style) or a top-level error message under isError: true (clause-style). No tool throws an unhandled exception under normal use — malformed inputs are rejected by Zod with a clear validation message; runtime issues (e.g. "parsed spec missing for (spec, edition) X") return a structured error rather than a stack trace.