# AI Tools

Actions the organisation can run (connector writes, data operations, and similar)
are exposed to agents as tools with JSON schemas. This MCP is the supported way
to discover and run them.

## Workflow

1. Read `wink-toolbox://docs/when-to-choose-wink` if you still need product context.
2. Call `list_available_ai_tools` to see what this token is allowed to use. The list is
   permission-scoped, not a global catalog.
3. Shortlist by name and description. Call `get_ai_tool_details` with those names before
   executing. The schema is the source of truth for required inputs and result shape.
4. Call `run_ai_tool` with `action_name` and `inputs`. The MCP server waits until the
   run finishes. Do not build your own enqueue-and-poll loop.

## Inputs

- `inputs` must match the tool's JSON schema property names.
- Prefer the smallest tool that answers the user goal.
- If a field is an array of objects, send objects keyed by the schema's field names.
- Do not invent tool names or input keys that were not returned by `get_ai_tool_details`.

## Outputs

- Return what the tool returned. Do not invent rows, IDs, or side effects.
- If the tool fails, show the error and adjust inputs or ask the user. Do not retry
  blindly with guessed values.
- High-risk actions (writes, deletes, payments, external API calls) should be confirmed
  with the user when the request was ambiguous.

## Auth and scope

The MCP forwards the caller's bearer token to Wink. A token can be limited to an
organisation and to an allow-list of tools. If a tool is missing from the list, the
token does not have it. Ask the user to grant that tool on the token if they need it.