The root-tool contract: what a tool def must carry to be served at an MCP
root tools/list.
A root tool needs a non-blank :name and :description and an :inputSchema of type "object" with at least one property. Anything less is a VIOLATION. A property without a :description is a WARNING.
Enforcement points, all reading RootToolDef:
host registration assert-root-tool! / assert-root-tools!
load / compile time def-root-tool
an addon's CI hive-addon.tool-contract.test/deftest-root-tools,
hive-addon.tool-contract.check/-main
The root-tool contract: what a tool def must carry to be served at an MCP
root `tools/list`.
A root tool needs a non-blank :name and :description and an :inputSchema of
type "object" with at least one property. Anything less is a VIOLATION.
A property without a :description is a WARNING.
Enforcement points, all reading `RootToolDef`:
host registration `assert-root-tool!` / `assert-root-tools!`
load / compile time `def-root-tool`
an addon's CI `hive-addon.tool-contract.test/deftest-root-tools`,
`hive-addon.tool-contract.check/-main`(assert-root-tool! tool)Return tool when it conforms; throw ex-info
{:type :hive-addon/root-tool-contract :violations {label [Finding]}} otherwise.
Return `tool` when it conforms; throw ex-info
{:type :hive-addon/root-tool-contract :violations {label [Finding]}} otherwise.(assert-root-tools! tools)Return tools when every tool conforms; otherwise throw ONE ex-info naming
every offending tool (same ex-data shape as assert-root-tool!).
Return `tools` when every tool conforms; otherwise throw ONE ex-info naming every offending tool (same ex-data shape as `assert-root-tool!`).
(conforms? tool)True when tool has no contract violations.
True when `tool` has no contract violations.
(def-root-tool sym tool-def)Def sym to tool-def, checked against the root-tool contract.
A map literal is checked at macroexpansion, so a violation the source
text already decides fails compilation; the evaluated value is checked
again when the def runs.
Def `sym` to `tool-def`, checked against the root-tool contract. A map literal is checked at macroexpansion, so a violation the source text already decides fails compilation; the evaluated value is checked again when the def runs.
(expansion-view form)The tool def as far as source text decides it: a map literal with each
non-literal contract value replaced by a conforming stand-in. nil when
form is not a map literal.
The tool def as far as source text decides it: a map literal with each non-literal contract value replaced by a conforming stand-in. nil when `form` is not a map literal.
One contract finding: where it is and what is wrong.
One contract finding: where it is and what is wrong.
(format-findings label->findings)Render {label [Finding]} as one line per finding.
Render {label [Finding]} as one line per finding.
(literal-form? form)True when form contains no symbol and no list: its value is the form.
True when `form` contains no symbol and no list: its value is the form.
A string with at least one non-whitespace character.
A string with at least one non-whitespace character.
The :properties of a root tool's :inputSchema. Never empty.
The :properties of a root tool's :inputSchema. Never empty.
One property's JSON schema. Open: any JSON-schema keys are allowed.
One property's JSON schema. Open: any JSON-schema keys are allowed.
A JSON-schema property key, as a string or keyword.
A JSON-schema property key, as a string or keyword.
(report tools)Check every tool in tools.
=> {:checked n :violations {label [Finding]} :warnings {label [Finding]}}
Check every tool in `tools`.
=> {:checked n :violations {label [Finding]} :warnings {label [Finding]}}The :inputSchema a root tool must carry.
The :inputSchema a root tool must carry.
A tool def fit for an MCP root. Open: hosts and addons add keys.
A tool def fit for an MCP root. Open: hosts and addons add keys.
(tool-label tool)The tool's :name for messages, or a placeholder when it has none.
The tool's :name for messages, or a placeholder when it has none.
(violations tool)Contract violations of tool as a vector of Findings; [] when it conforms.
Contract violations of `tool` as a vector of Findings; [] when it conforms.
(warnings tool)Advisory findings of tool: each property lacking a non-blank :description.
Advisory findings of `tool`: each property lacking a non-blank :description.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |