# `OzMcp.Config.Tool.DSL`
[🔗](https://github.com/oz-elixir/oz_mcp/blob/v0.9.0/lib/oz_mcp/config/tool/dsl.ex#L6)

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

| Macro | Block | Value | Wire field |
|---|---|---|---|
| `tool "name"` | root | 1 to 128 characters of `A-Za-z0-9_.-`, unique in the module | `name` |
| `title` | `tool`, `annotations` | non-empty string | `title` |
| `description` | `tool` | non-empty string | `description` |
| `required_scopes` | `tool` | list of scope tokens | none (a `403` and a filtered `tools/list`) |
| `input_schema` | `tool` | JSON Schema map, not empty, with the type `"object"` at the root (the default is `{"type":"object","properties":{}}`) | `inputSchema` |
| `output_schema` | `tool` | JSON Schema map, not empty, with the type `"object"` at the root | `outputSchema` |
| `annotations` | `tool` | block | `annotations` |
| `read_only_hint`, `destructive_hint`, `idempotent_hint`, `open_world_hint` | `annotations` | boolean | `annotations.readOnlyHint` and so on |
| `execution` | `tool` | block | `execution` |
| `task_support` | `execution` | `"forbidden"`, `"optional"` or `"required"` | `execution.taskSupport` |
| `poll_interval` | `execution` | positive integer (ms) | none (the `pollInterval` hint of the task records of the tool) |
| `immediate_response` | `execution` | non-empty string | none (the `io.modelcontextprotocol/model-immediate-response` text of the `CreateTaskResult`) |
| `icon` | `tool` (repeatable) | block | one entry of `icons` |
| `src` | `icon` | `https:` URL, `http:` URL of a loopback host, or `data:` URI | `icons[].src` |
| `mime_type` | `icon` | non-empty string | `icons[].mimeType` |
| `sizes` | `icon` | list of `"any"` and `"WxH"` strings | `icons[].sizes` |
| `theme` | `icon` | `"light"` or `"dark"` | `icons[].theme` |
| `meta key, value` | `tool` | key: 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](guides/entities/tools.md) shows an example of the
DSL.

# `annotations`
*macro* 

# `description`
*macro* 

# `destructive_hint`
*macro* 

# `execution`
*macro* 

# `icon`
*macro* 

# `idempotent_hint`
*macro* 

# `immediate_response`
*macro* 

# `input_schema`
*macro* 

# `meta`
*macro* 

# `mime_type`
*macro* 

# `open_world_hint`
*macro* 

# `output_schema`
*macro* 

# `poll_interval`
*macro* 

# `read_only_hint`
*macro* 

# `required_scopes`
*macro* 

# `sizes`
*macro* 

# `src`
*macro* 

# `task_support`
*macro* 

# `theme`
*macro* 

# `title`
*macro* 

# `tool`
*macro* 

---

*Consult [api-reference.md](api-reference.md) for complete listing*
