AI (opt-in)

AI custom tools

Get AI Custom Tool Guide

discourse_ai_get_custom_tool_guide

Retrieve one focused MiniRacer authoring topic. Usually pass only topic. preset_id is optional and used only with topic=presets to load one live example; extra preset_id values on other topics are ignored. Requires admin credentials.

Get AI Custom Tool Guide

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_ai_get_custom_tool_guide",
    "arguments": {
        "topic": "overview",
        "preset_id": "string"
      }
  }
}

const result = await client.callTool({
  "name": "discourse_ai_get_custom_tool_guide",
  "arguments": {
    "topic": "overview",
    "preset_id": "string"
  }
});

result = await session.call_tool("discourse_ai_get_custom_tool_guide", arguments={
  "topic": "overview",
  "preset_id": "string"
})

Parameters

topicstringoverviewpreambleentrypointsparametershttpllmraguploadschainsecretsdiscoursecontextcryptolimitssecuritypresetsoverview

Focused guide section. Use presets to browse or retrieve live preset examples.

preset_idstring

Optional live preset ID used only when topic=presets; ignored for every other topic.

List AI Custom Tools

discourse_ai_list_custom_tools

List concise database-backed custom-tool summaries and compact live preset metadata. Scripts, bindings, verbose parameter descriptions, and full records are omitted; use discourse_ai_get_custom_tool or the guide's preset lookup to zoom in. Requires admin credentials.

List AI Custom Tools

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_ai_list_custom_tools",
    "arguments": {}
  }
}

const result = await client.callTool({
  "name": "discourse_ai_list_custom_tools",
  "arguments": {}
});

result = await session.call_tool("discourse_ai_list_custom_tools", arguments={})

Get AI Custom Tool

discourse_ai_get_custom_tool

Get one database-backed scripted AI tool, including source and configured secret bindings. Treat the response as sensitive. Requires admin credentials.

Get AI Custom Tool

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_ai_get_custom_tool",
    "arguments": {
        "id": 0
      }
  }
}

const result = await client.callTool({
  "name": "discourse_ai_get_custom_tool",
  "arguments": {
    "id": 0
  }
});

result = await session.call_tool("discourse_ai_get_custom_tool", arguments={
  "id": 0
})

Request Body

{
  "id": 0
}

Body

application/json

idinteger | stringrequired

Show child attributes

Any of

integer

string

Create AI Custom Tool

discourse_ai_create_custom_tool

Create a database-backed synchronous MiniRacer scripted tool. Call discourse_ai_get_custom_tool_guide before authoring. Never provide raw secret values. Requires admin credentials and write mode.

Create AI Custom Tool

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_ai_create_custom_tool",
    "arguments": {
        "name": "string",
        "tool_name": "string",
        "description": "string",
        "summary": "string",
        "script": "string",
        "parameters": [
          {
            "name": "string",
            "type": "string",
            "description": "string",
            "required": true,
            "enum": [
              "string"
            ]
          }
        ],
        "secret_contracts": [
          {
            "alias": "string"
          }
        ],
        "secret_bindings": [
          {
            "alias": "string",
            "ai_secret_id": 0
          }
        ],
        "rag_chunk_tokens": 1,
        "rag_chunk_overlap_tokens": 0,
        "rag_llm_model_id": 0,
        "rag_uploads": [
          {
            "id": 0
          }
        ]
      }
  }
}

const result = await client.callTool({
  "name": "discourse_ai_create_custom_tool",
  "arguments": {
    "name": "string",
    "tool_name": "string",
    "description": "string",
    "summary": "string",
    "script": "string",
    "parameters": [
      {
        "name": "string",
        "type": "string",
        "description": "string",
        "required": true,
        "enum": [
          "string"
        ]
      }
    ],
    "secret_contracts": [
      {
        "alias": "string"
      }
    ],
    "secret_bindings": [
      {
        "alias": "string",
        "ai_secret_id": 0
      }
    ],
    "rag_chunk_tokens": 1,
    "rag_chunk_overlap_tokens": 0,
    "rag_llm_model_id": 0,
    "rag_uploads": [
      {
        "id": 0
      }
    ]
  }
});

result = await session.call_tool("discourse_ai_create_custom_tool", arguments={
  "name": "string",
  "tool_name": "string",
  "description": "string",
  "summary": "string",
  "script": "string",
  "parameters": [
    {
      "name": "string",
      "type": "string",
      "description": "string",
      "required": true,
      "enum": [
        "string"
      ]
    }
  ],
  "secret_contracts": [
    {
      "alias": "string"
    }
  ],
  "secret_bindings": [
    {
      "alias": "string",
      "ai_secret_id": 0
    }
  ],
  "rag_chunk_tokens": 1,
  "rag_chunk_overlap_tokens": 0,
  "rag_llm_model_id": 0,
  "rag_uploads": [
    {
      "id": 0
    }
  ]
})

Request Body

{
  "name": "string",
  "tool_name": "string",
  "description": "string",
  "summary": "string",
  "script": "string",
  "parameters": [
    {
      "name": "string",
      "type": "string",
      "description": "string",
      "required": true,
      "enum": [
        "string"
      ]
    }
  ],
  "secret_contracts": [
    {
      "alias": "string"
    }
  ],
  "secret_bindings": [
    {
      "alias": "string",
      "ai_secret_id": 0
    }
  ],
  "rag_chunk_tokens": 1,
  "rag_chunk_overlap_tokens": 0,
  "rag_llm_model_id": 0,
  "rag_uploads": [
    {
      "id": 0
    }
  ]
}

Body

application/json

namestringrequired

tool_namestringrequired

descriptionstringrequired

summarystringrequired

scriptstringrequired

parametersArray<object>

Show child attributes

namestringrequired

typestringstringnumberbooleanarrayrequired

descriptionstringrequired

requiredbooleanrequired

enumArray<string | number>

secret_contractsArray<object>

Show child attributes

aliasstringrequired

secret_bindingsArray<object>

Show child attributes

aliasstringrequired

ai_secret_idinteger | nullrequired

Show child attributes

Any of

integer

null

rag_chunk_tokensinteger[1, 50000]

rag_chunk_overlap_tokensinteger[0, 200]

rag_llm_model_idinteger | null

Show child attributes

Any of

integer

null

rag_uploadsArray<object>

Show child attributes

idintegerrequired

Update AI Custom Tool

discourse_ai_update_custom_tool

Partially update a scripted tool. Call the guide before substantial script changes. Omitted scalar fields and RAG uploads are preserved; changing secret_contracts can prune orphan bindings unless secret_bindings are supplied. Raw secret values are never accepted. Requires admin credentials and write mode.

Update AI Custom Tool

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_ai_update_custom_tool",
    "arguments": {
        "id": 0,
        "name": "string",
        "tool_name": "string",
        "description": "string",
        "summary": "string",
        "script": "string",
        "parameters": [
          {
            "name": "string",
            "type": "string",
            "description": "string",
            "required": true,
            "enum": [
              "string"
            ]
          }
        ],
        "secret_contracts": [
          {
            "alias": "string"
          }
        ],
        "secret_bindings": [
          {
            "alias": "string",
            "ai_secret_id": 0
          }
        ],
        "rag_chunk_tokens": 1,
        "rag_chunk_overlap_tokens": 0,
        "rag_llm_model_id": 0,
        "rag_uploads": [
          {
            "id": 0
          }
        ]
      }
  }
}

const result = await client.callTool({
  "name": "discourse_ai_update_custom_tool",
  "arguments": {
    "id": 0,
    "name": "string",
    "tool_name": "string",
    "description": "string",
    "summary": "string",
    "script": "string",
    "parameters": [
      {
        "name": "string",
        "type": "string",
        "description": "string",
        "required": true,
        "enum": [
          "string"
        ]
      }
    ],
    "secret_contracts": [
      {
        "alias": "string"
      }
    ],
    "secret_bindings": [
      {
        "alias": "string",
        "ai_secret_id": 0
      }
    ],
    "rag_chunk_tokens": 1,
    "rag_chunk_overlap_tokens": 0,
    "rag_llm_model_id": 0,
    "rag_uploads": [
      {
        "id": 0
      }
    ]
  }
});

result = await session.call_tool("discourse_ai_update_custom_tool", arguments={
  "id": 0,
  "name": "string",
  "tool_name": "string",
  "description": "string",
  "summary": "string",
  "script": "string",
  "parameters": [
    {
      "name": "string",
      "type": "string",
      "description": "string",
      "required": true,
      "enum": [
        "string"
      ]
    }
  ],
  "secret_contracts": [
    {
      "alias": "string"
    }
  ],
  "secret_bindings": [
    {
      "alias": "string",
      "ai_secret_id": 0
    }
  ],
  "rag_chunk_tokens": 1,
  "rag_chunk_overlap_tokens": 0,
  "rag_llm_model_id": 0,
  "rag_uploads": [
    {
      "id": 0
    }
  ]
})

Request Body

{
  "id": 0,
  "name": "string",
  "tool_name": "string",
  "description": "string",
  "summary": "string",
  "script": "string",
  "parameters": [
    {
      "name": "string",
      "type": "string",
      "description": "string",
      "required": true,
      "enum": [
        "string"
      ]
    }
  ],
  "secret_contracts": [
    {
      "alias": "string"
    }
  ],
  "secret_bindings": [
    {
      "alias": "string",
      "ai_secret_id": 0
    }
  ],
  "rag_chunk_tokens": 1,
  "rag_chunk_overlap_tokens": 0,
  "rag_llm_model_id": 0,
  "rag_uploads": [
    {
      "id": 0
    }
  ]
}

Body

application/json

idinteger | stringrequired

Show child attributes

Any of

integer

string

namestring

tool_namestring

descriptionstring

summarystring

scriptstring

parametersArray<object>

Show child attributes

namestringrequired

typestringstringnumberbooleanarrayrequired

descriptionstringrequired

requiredbooleanrequired

enumArray<string | number>

secret_contractsArray<object>

Show child attributes

aliasstringrequired

secret_bindingsArray<object>

Show child attributes

aliasstringrequired

ai_secret_idinteger | nullrequired

Show child attributes

Any of

integer

null

rag_chunk_tokensinteger[1, 50000]

rag_chunk_overlap_tokensinteger[0, 200]

rag_llm_model_idinteger | null

Show child attributes

Any of

integer

null

rag_uploadsArray<object>

Show child attributes

idintegerrequired

Delete AI Custom Tool

destructive

discourse_ai_delete_custom_tool

Delete a scripted tool. Agents referencing it may stop functioning as configured. Requires admin credentials and write mode.

Delete AI Custom Tool

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_ai_delete_custom_tool",
    "arguments": {
        "id": 0
      }
  }
}

const result = await client.callTool({
  "name": "discourse_ai_delete_custom_tool",
  "arguments": {
    "id": 0
  }
});

result = await session.call_tool("discourse_ai_delete_custom_tool", arguments={
  "id": 0
})

Request Body

{
  "id": 0
}

Body

application/json

idinteger | stringrequired

Show child attributes

Any of

integer

string

Test AI Custom Tool

discourse_ai_test_custom_tool

Actually execute a persisted or unsaved custom-tool script. It can make external requests and cause side effects; this is not dry validation. Requires admin credentials and write mode.

Test AI Custom Tool

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_ai_test_custom_tool",
    "arguments": {
        "id": 0,
        "parameters": {},
        "script": "string",
        "secret_bindings": [
          {
            "alias": "string",
            "ai_secret_id": 0
          }
        ]
      }
  }
}

const result = await client.callTool({
  "name": "discourse_ai_test_custom_tool",
  "arguments": {
    "id": 0,
    "parameters": {},
    "script": "string",
    "secret_bindings": [
      {
        "alias": "string",
        "ai_secret_id": 0
      }
    ]
  }
});

result = await session.call_tool("discourse_ai_test_custom_tool", arguments={
  "id": 0,
  "parameters": {},
  "script": "string",
  "secret_bindings": [
    {
      "alias": "string",
      "ai_secret_id": 0
    }
  ]
})

Request Body

{
  "id": 0,
  "parameters": {},
  "script": "string",
  "secret_bindings": [
    {
      "alias": "string",
      "ai_secret_id": 0
    }
  ]
}

Body

application/json

idinteger | stringrequired

Show child attributes

Any of

integer

string

parametersobject[object Object]

Show child attributes

[key: string]any

scriptstring

secret_bindingsArray<object>

Show child attributes

aliasstringrequired

ai_secret_idinteger | nullrequired

Show child attributes

Any of

integer

null

Export AI Custom Tool

discourse_ai_export_custom_tool

Export portable custom-tool JSON. Discourse excludes secret bindings; MCP also strips them defensively. Treat script source as sensitive. Requires admin credentials.

Export AI Custom Tool

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_ai_export_custom_tool",
    "arguments": {
        "id": 0
      }
  }
}

const result = await client.callTool({
  "name": "discourse_ai_export_custom_tool",
  "arguments": {
    "id": 0
  }
});

result = await session.call_tool("discourse_ai_export_custom_tool", arguments={
  "id": 0
})

Request Body

{
  "id": 0
}

Body

application/json

idinteger | stringrequired

Show child attributes

Any of

integer

string

Import AI Custom Tool

destructive

discourse_ai_import_custom_tool

Import portable custom-tool JSON. force overwrites a matching tool_name and requires confirm_force=true. Secret IDs may be bound, but raw secret values are never accepted. Requires admin credentials and write mode.

Import AI Custom Tool

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_ai_import_custom_tool",
    "arguments": {
        "ai_tool": {
          "name": "string",
          "tool_name": "string",
          "description": "string",
          "summary": "string",
          "script": "string",
          "parameters": [
            {
              "name": "string",
              "type": "string",
              "description": "string",
              "required": true,
              "enum": [
                "string"
              ]
            }
          ],
          "secret_contracts": [
            {
              "alias": "string"
            }
          ],
          "secret_bindings": [
            {
              "alias": "string",
              "ai_secret_id": 0
            }
          ],
          "rag_chunk_tokens": 1,
          "rag_chunk_overlap_tokens": 0,
          "rag_llm_model_id": 0,
          "rag_uploads": [
            {
              "id": 0
            }
          ],
          "id": 0,
          "created_by_id": 0,
          "created_at": "string",
          "updated_at": "string"
        },
        "force": false,
        "confirm_force": false
      }
  }
}

const result = await client.callTool({
  "name": "discourse_ai_import_custom_tool",
  "arguments": {
    "ai_tool": {
      "name": "string",
      "tool_name": "string",
      "description": "string",
      "summary": "string",
      "script": "string",
      "parameters": [
        {
          "name": "string",
          "type": "string",
          "description": "string",
          "required": true,
          "enum": [
            "string"
          ]
        }
      ],
      "secret_contracts": [
        {
          "alias": "string"
        }
      ],
      "secret_bindings": [
        {
          "alias": "string",
          "ai_secret_id": 0
        }
      ],
      "rag_chunk_tokens": 1,
      "rag_chunk_overlap_tokens": 0,
      "rag_llm_model_id": 0,
      "rag_uploads": [
        {
          "id": 0
        }
      ],
      "id": 0,
      "created_by_id": 0,
      "created_at": "string",
      "updated_at": "string"
    },
    "force": false,
    "confirm_force": false
  }
});

result = await session.call_tool("discourse_ai_import_custom_tool", arguments={
  "ai_tool": {
    "name": "string",
    "tool_name": "string",
    "description": "string",
    "summary": "string",
    "script": "string",
    "parameters": [
      {
        "name": "string",
        "type": "string",
        "description": "string",
        "required": true,
        "enum": [
          "string"
        ]
      }
    ],
    "secret_contracts": [
      {
        "alias": "string"
      }
    ],
    "secret_bindings": [
      {
        "alias": "string",
        "ai_secret_id": 0
      }
    ],
    "rag_chunk_tokens": 1,
    "rag_chunk_overlap_tokens": 0,
    "rag_llm_model_id": 0,
    "rag_uploads": [
      {
        "id": 0
      }
    ],
    "id": 0,
    "created_by_id": 0,
    "created_at": "string",
    "updated_at": "string"
  },
  "force": false,
  "confirm_force": false
})

Request Body

{
  "ai_tool": {
    "name": "string",
    "tool_name": "string",
    "description": "string",
    "summary": "string",
    "script": "string",
    "parameters": [
      {
        "name": "string",
        "type": "string",
        "description": "string",
        "required": true,
        "enum": [
          "string"
        ]
      }
    ],
    "secret_contracts": [
      {
        "alias": "string"
      }
    ],
    "secret_bindings": [
      {
        "alias": "string",
        "ai_secret_id": 0
      }
    ],
    "rag_chunk_tokens": 1,
    "rag_chunk_overlap_tokens": 0,
    "rag_llm_model_id": 0,
    "rag_uploads": [
      {
        "id": 0
      }
    ],
    "id": 0,
    "created_by_id": 0,
    "created_at": "string",
    "updated_at": "string"
  },
  "force": false,
  "confirm_force": false
}

Body

application/json

ai_toolobjectrequired

Show child attributes

namestringrequired

tool_namestringrequired

descriptionstringrequired

summarystringrequired

scriptstringrequired

parametersArray<object>

Show child attributes

namestringrequired

typestringstringnumberbooleanarrayrequired

descriptionstringrequired

requiredbooleanrequired

enumArray<string | number>

secret_contractsArray<object>

Show child attributes

aliasstringrequired

secret_bindingsArray<object>

Show child attributes

aliasstringrequired

ai_secret_idinteger | nullrequired

Show child attributes

Any of

integer

null

rag_chunk_tokensinteger[1, 50000]

rag_chunk_overlap_tokensinteger[0, 200]

rag_llm_model_idinteger | null

Show child attributes

Any of

integer

null

rag_uploadsArray<object>

Show child attributes

idintegerrequired

idinteger

created_by_idinteger

created_atstring

updated_atstring

forcebooleanfalse

confirm_forcebooleanfalse

Docs by Sourcey