OzMcp.Config.Tool.DSL (OzMcp v0.9.0)

Copy Markdown View Source

Compile-time macros of a tool module (use OzMcp.Config.Tool).

use OzMcp.Config.Tool imports the root macro tool/2 only. The nested macros are not imported: they work only inside their tool block. A nested macro at the root of the module gives a compile error (undefined function title/1).

The macros generate list/0 of the tool behaviour. The module must define call/2. A module with the DSL cannot define list/0.

The macros

MacroBlockValueWire field
tool "name"root1 to 128 characters of A-Za-z0-9_.-, unique in the modulename
titletool, annotationsnon-empty stringtitle
descriptiontoolnon-empty stringdescription
required_scopestoollist of scope tokensnone (a 403 and a filtered tools/list)
input_schematoolJSON Schema map, not empty, with the type "object" at the root (the default is {"type":"object","properties":{}})inputSchema
output_schematoolJSON Schema map, not empty, with the type "object" at the rootoutputSchema
annotationstoolblockannotations
read_only_hint, destructive_hint, idempotent_hint, open_world_hintannotationsbooleanannotations.readOnlyHint and so on
executiontoolblockexecution
task_supportexecution"forbidden", "optional" or "required"execution.taskSupport
poll_intervalexecutionpositive integer (ms)none (the pollInterval hint of the task records of the tool)
immediate_responseexecutionnon-empty stringnone (the io.modelcontextprotocol/model-immediate-response text of the CreateTaskResult)
icontool (repeatable)blockone entry of icons
srciconhttps: URL, http: URL of a loopback host, or data: URIicons[].src
mime_typeiconnon-empty stringicons[].mimeType
sizesiconlist of "any" and "WxH" stringsicons[].sizes
themeicon"light" or "dark"icons[].theme
meta key, valuetoolkey: string or atom, value: a JSON term_meta.<key>

A wrong value, a macro outside its block, or a property declared two times raises at compile time. An input_schema and an output_schema that the JSON Schema validator refuses raise at compile time too. With warn?: true (the default), a tool with no title or no description gives a compiler warning and a name outside the rule of the table gives a compiler warning too (an error with strict_names?: true).

The guide Tools shows an example of the DSL.

Summary

Functions

annotations(list)

(macro)

description(value)

(macro)

destructive_hint(value)

(macro)

execution(list)

(macro)

icon(list)

(macro)

idempotent_hint(value)

(macro)

immediate_response(value)

(macro)

input_schema(value)

(macro)

meta(key, value)

(macro)

mime_type(value)

(macro)

open_world_hint(value)

(macro)

output_schema(value)

(macro)

poll_interval(value)

(macro)

read_only_hint(value)

(macro)

required_scopes(value)

(macro)

sizes(value)

(macro)

src(value)

(macro)

task_support(value)

(macro)

theme(value)

(macro)

title(value)

(macro)

tool(entity_name, list)

(macro)