Module arguments 

Argument-shape errors (spec/surface/README.md §4 “Arguments”, 3.0): every tool call is checked against its ToolSpec’s JSON schema ahead of dispatch, and a malformed call is one filter_invalid whose message names what was expected — and, for an unknown argument name, the nearest valid one. The reference (packages/core/src/mcp/arguments.ts) composes the same messages byte for byte and the surface fixtures pin them (every argument-shape error carries data.hint = "arguments").

Message forms (the (… takes …) tail lists the tool’s arguments in bytewise order, optional ones marked ?; a tool without arguments “takes no arguments”):

unknown argument `q`; did you mean `query`? (blocks_search takes limit?, q, repo?)
`doc` is no longer an argument — pass `id` or `path` (docs_read takes …)
`query` is required (query takes …)
`limit` must be an integer (query takes …)
pass id or path (docs_read takes …)                      — a locator tool called with neither
id "d_x" and path "/a.md" name different documents (…)    — both given, disagreeing

Enums

JsonArrayString

What a string opening [ in a string-list slot reads as (4.11, the reference’s jsonArrayString).

Constants

DRY_RUN_RETIRED

dry_run on apply and every sugar tool (4.0): the preview is plan.

OPS_RETIRED

apply { ops } (4.0, spec/surface §4): the kernel ops apply took through 3.x are a library/fixture contract (spec/mutate §4).

Functions

argument_error

A filter_invalid for an argument-shape failure: message plus the tool’s shape.

argument_error_fix

argument_error with a fix (4.5, spec/surface §4 “Arguments”) when the corrected call can be spelled.

arguments_hint

The (tool takes …) tail: property names in bytewise order, ? on the ones not in required.

comma_split

The parts of a comma-joined string: split on ,, trimmed, empty parts dropped.

json_array_string

A string whose trimmed form opens [, read as JSON; None when it does not open [ (the 4.5 rules apply unchanged).

levenshtein

nearest

The nearest candidate: Levenshtein distance ≤ 2, or a prefix relation either way; ties → the bytewise-first.

phrase_for

The expected-type phrase of an argument, as the reference spells it from its zod schema.

unknown_argument_message

What to say about an argument name the tool does not take: the names 3.0 retired are called out with their replacement (doc → id/path, block/node → id, heading → section, markdown → text) when the tool has the replacement, and so are the inputs 4.0 retired — ops (where the tool takes effects: the kernel ops are a library/fixture contract), dry_run (every preview is plan), attrs (where the tool takes checked); otherwise the nearest valid name (Levenshtein ≤ 2, or one a prefix of the other).

validate_arguments

Check args against the tool’s schema: unknown names first (bytewise order), then each declared argument (bytewise order) for presence and type. Nested shapes (ops, expect, at) are checked by their handlers. Returns the arguments as the handler sees them when the check normalized one (4.5: a bare string in a string-list slot becomes [s]), else None.