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

Behaviour for MCP tool modules.

## Two ways to declare the tools

| Way | `use` | What you write | What the framework generates |
|---|---|---|---|
| DSL | `use OzMcp.Config.Tool` | one `tool "name" do ... end` block for each tool and `call/2` | `list/0`. The DSL checks the schemas at compile time. |
| Data | `use OzMcp.Config.Tool, dsl?: false` | `list/0` that returns `%OzMcp.Structs.Tool{}` structs or maps with the wire keys (`name`, `inputSchema`, ...) and `call/2` | nothing |

Rules for the way with `dsl?: false`:

  * A map carries `required_scopes` like a struct: the boot of the
    instance reads the key, checks it and it never reaches the
    client.
  * The boot check of duplicate names reads `list/0` of a module one
    time at boot.

The guide [Tools](guides/entities/tools.md) shows an example of each
way.

## Static schemas and schema validation

The server reads a module one time, at the boot of the instance and
answers a lookup from a map in the catalog. A change of a module
needs a stop and a start of the instance.

A `dsl?: true` tool (the default) that declares an invalid
`inputSchema` or `outputSchema` fails at compile time; the root of
each schema must have the type `"object"`. A tool with `dsl?: false`
is checked at the boot of the instance. The guide
[Tools](guides/entities/tools.md) gives the details of each check.

## Output schema

When a tool declares an `outputSchema`, the server checks each result
of the tool before it sends the result:

  * A result with `isError: true` is not checked.
  * Each other result must have a `structuredContent` that is an
    object and that agrees with the `outputSchema`.
  * The check uses the JSON form of `structuredContent`: atom keys and
    atom values are strings, as on the wire.

A result that does not obey these rules gives the JSON-RPC error
`-32603` `"tool output does not match outputSchema"`. The `data` of
the error holds the messages. A task-augmented call gets the same
check: the task becomes `failed` and `tasks/result` gives the same
error.

## Required scopes

Declare `required_scopes [...]` in a `tool` block: a `tools/call`
without all the scopes gets `403` and `tools/list` hides the tool
from a principal that lacks them. A tool declared with `dsl?: false`
carries the scopes in the key `required_scopes` of a map, or in the
field of the struct. The guide about the authorization gives the
rules of the scopes and of the filter of the lists.

## Unique key

The `name` of a tool is unique in the module: two tools with the same
`name` raise at compile time. The `name` is unique in the server too:
the runtime refuses to boot when two tool modules of one server
declare the same `name`. The boot check reads `list/0` of each
module.

# `call_result`

```elixir
@type call_result() ::
  {:ok,
   %OzMcp.Structs.CallToolResult{
     _meta: term(),
     content: term(),
     extras: term(),
     isError: term(),
     structuredContent: term()
   }}
  | {:ok, map()}
  | {:error, %OzMcp.Utils.Error{code: term(), data: term(), message: term()}}
```

# `name`

```elixir
@type name() :: String.t()
```

# `rpc_params`

```elixir
@type rpc_params() :: map()
```

# `call`

```elixir
@callback call(OzMcp.Context.ctx(), rpc_params()) :: call_result()
```

Runs the tool `params["name"]` with the arguments
`params["arguments"]`.

`params` is the full `params` object of `tools/call`. The input
schema of the tool checked the arguments and gave the default
values, before the call.

Return:

  * `{:ok, %CallToolResult{}}` or `{:ok, map}`: the result of the
    tool. Set `isError: true` for an error that the model can
    correct.
  * `{:error, %OzMcp.Utils.Error{}}`: a protocol error, for example
    an unknown tool (`-32602`).

Each other return value gives the client a `-32603` error. The
callback runs in a supervised process of its own, after the request
process.

## Example

    @impl true
    def call(_ctx, %{"name" => "echo", "arguments" => %{"text" => text}}) do
      {:ok, %{content: [%{type: "text", text: text}]}}
    end

# `list`

```elixir
@callback list() ::
  [
    %OzMcp.Structs.Tool{
      _meta: term(),
      annotations: term(),
      description: term(),
      execution: term(),
      extras: term(),
      icons: term(),
      inputSchema: term(),
      name: term(),
      outputSchema: term(),
      required_scopes: term(),
      title: term()
    }
  ]
  | [map()]
```

Returns the tools of the module: `%OzMcp.Structs.Tool{}` structs, or
maps with the wire keys.

The DSL generates it. The boot of the instance calls it one time.

---

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