diff --git a/docs/tools/adding-tools.mdx b/docs/tools/adding-tools.mdx
index 9027c98a..8081ffe0 100644
--- a/docs/tools/adding-tools.mdx
+++ b/docs/tools/adding-tools.mdx
@@ -1,4 +1,4 @@
-# Adding Tools
+# Adding tools
By default, there are no pre-connected tools in Superface, so to get started you need to add them.
@@ -72,3 +72,15 @@ If a tool has not been fully set up, a red dot will be shown next to the name.
To check for any issues, or to continue with configuration for the tool, click on _Config_.
+
+## Create new/custom use cases
+
+It is possible to add new use cases to the tools provided by Superface using the Authoring Hub. Any tool that supports this will have an square block icon next to the name (as shown below).
+
+
+
+Click on the name of the tool to open the Config page. You can then start creating your custom use case by clicking the _Add custom use case_ button.
+
+
+
+You can find out more about creating custom use cases and entirely new tools for use with Superface in our [Create Tools](./create-tools) guide.
diff --git a/docs/tools/available-tools.mdx b/docs/tools/available-tools.mdx
index b3788258..5316ec44 100644
--- a/docs/tools/available-tools.mdx
+++ b/docs/tools/available-tools.mdx
@@ -2,4 +2,6 @@ import DocCardList from '@theme/DocCardList';
# Tools
+The ready made tools available in Superface are:
+
diff --git a/docs/tools/create-tools.mdx b/docs/tools/create-tools.mdx
index 79c101f8..787652e3 100644
--- a/docs/tools/create-tools.mdx
+++ b/docs/tools/create-tools.mdx
@@ -1,30 +1,40 @@
-# Creating Tools
+# Creating tools
-Superface offers a web based builder named _Authoring_ Hub that uses Open API Specification files to generate tools that you can add to your account for use with your GPT or Agent.
+Superface offers a web based tool builder that allows you to:
-You can launch the Authoring Hub by clicking on _Create Tools_ in your Account menu, or by heading to [https://pod.superface.ai/authoring](https://pod.superface.ai/authoring).
+- Create new tools for specific providers such as Slack, Resend or Pipedrive.
+- Create any new tools you need using Open API Specifications.
-
+Access the Authoring Hub by clicking on _Create Tools_ in your Account menu, or by heading to [https://pod.superface.ai/authoring](https://pod.superface.ai/authoring).
-If it is your first time creating a tool, there won't be much to look at.
+
-The first step is to add a _Provider_. This is the Open API Specification for the platform or API you want to connect to Superface.
+If it is your first time creating a tool, you need to choose whether you want to add a tool that Superface does not currently support, or if you want to add a new use case for one of the existing Superface tools.
-## Step 1: Add a Provider
+- [I want to add something completely new](#add-a-new-tool)
+- [I want to add a use case for a Superface tool (start from step 3)](#step-3-create-a-use-case)
-Start by clicking on **+ Provider**, a popup will appear and you can either paste an Open API Specification, or provide a URL for one (URLs for documentation hosted by Readme.io will also be accepted here).
+## Add a new use case/tool
-
+:::info Requirements
+In order to add a new tool to Superface you will need a URL or a copy of the Open API Specification for the API of the service you want to connect to.
+:::
+
+### Step 1: Upload documentation
+
+Start by clicking on **+ Add tool**, a popup will appear and you can either paste an Open API Specification, or provide a URL for it (URLs for documentation hosted by Readme.io will also be accepted here).
+
+
You don't have to provide a name, however if you want control over the naming you can provide one. Typically the name should be for the service you are creating a tool for (eg. _electricity-maps, hubspot, my-company-api_).
-Clicking _Connect Provider_ will index the Open API Specification and get it ready for you to make a tool with. You will see the progress on your screen as well as any errors that may occur.
+Clicking _Connect tool_ will index the Open API Specification and get it ready for you to make a tool with. You will see the progress on your screen as well as any errors that may occur.
## Step 2: Check the provider
Once indexing is complete you will be redirected to a page similar to the one below.
-
+
You can check the setup for the Provider by looking at the JSON output. It outlines:
@@ -37,74 +47,52 @@ If you think anything is missing, you can add the elements you need by using the
-## Step 3: Create a tool
-
-If everything looks correct, it's time to create a tool!
+If everything looks correct, it's time to create your use case by clicking _Create use case_.
-In the _Create new tool_ section you can describe your use case in plain English, and Superface will work out how to achieve it using the Open API Specification you already provided.
+## Step 3: Create a use case
-For example, this _Electricity Maps_ example, we want to get the latest carbon intensity data for a particular zone, so our prompt can be:
+Before defining your use case, you must install the provider for the tool. You can do this by clicking on _Install_. Once complete, you can proceed with writing your use case prompt.
-
+
-Below the prompt is the provider you want to create the tool with (in this example, it's _electricity-maps_).
+Next, define what the action for your tool should take by writing it out as natural language. For example, with this _dbt_ tool, we want to invite new users to our account:
-### Scopes and names
+
-Superface uses scopes and names as part of the naming convention for the capabilities a tool can offer. You can provide scopes and names if you want, but we will also infer them from the information we have.
+Click **Create new use case** to continue.
-In this example, we are looking to get _intensity_ data about carbon use. There are other aspects of carbon data available too, such as _history_ so we could name this tool `carbon/intensity`. Later if we create a tool for historical carbon usage, we can name it `carbon/history`.
+Superface will then determine how to achieve your use case using the documentation you provided earlier.
-
+
-Click **Create** to create your new tool.
+## Step 4: Test and edit
-## Step 4: Map
+After Superface determines what is required by the API to achieve your use case, you will see a page that looks similar to the one below.
-After Superface determines what is required by the API to achieve your use case, you will see a page that looks similar to the one below, with areas for _Profile_, _Map_ and _Provider_.
+
-
+There are three areas on this page:
-Click on the _Select Provider_ drop down that is highlighted in red. Then select the provider you created earlier. This will then populate the Provider box on the screen.
+The **use case interface** defines the expected inputs that are needed to make your use case possible, as well as what a successful response will look like. This is determined from the documentation you provided.
-
+The **chat window** on the right is pre-populated with your requested use case prompt. You can test it directly from here to see if you get the response you are looking for.
-The _Profile_ was created by Superface, based on your earlier use case prompt. It outlines what inputs are required and what the result of a successful run should look like, along with example data that the AI can use to guide users to the correct inputs.
+First, test your prompt to see what you get.
-The final step in tool creation is to create a _Map_. This will build a function that will call the API directly to achieve your use case, based on the data in the _Profile_ and the _Provider_.
+
-Click **Map with AI** to start this process.
+In order to complete requests with your tool, Superface needs the correct authorization. If this is not already set up, you will be asked to configure it. Click on _Configure_ to enter the API credentials.
-
+If you are happy with the output from your prompt, you can move on to installing it.
-Again, you will see the progress as it happens, along with any errors.
-
-
+If you think your prompt can do better, you can choose to _Change the inital prompt_ and provide greater specificity.
## Step 5: Install your tool
-After the map has been created, your browser will return to the previous screen. The _Map_ section should now be populated.
+To install your tool click on _Install use case_. A modal will appear with the files that are going to be installed on your account. This is for information only.
-
+
Superface now has everything it needs to provide the capability you requested.
-Click on **Install** to add it to your list of added tools.
-
-
-
-As you can see in the image above, there is a red dot next to the tool name. This means that there is a piece of configuration missing.
-
-Click on _Config_ to add it and compete the setup.
-
-## Step 6: Configure your tool
-
-Typically, the final step will be to add any authentication information to the configuration for your tool. In this example, an API Key is required.
-
-
-
-Once the API Key is added, click on _Save Changes_.
-
-
-
-Green is good! The tool is setup and read for you to use with your GPT, or Agent.
+Click on **Install use case** again to add it to your list of tools.
diff --git a/docs/tools/editing-tools.mdx b/docs/tools/editing-tools.mdx
new file mode 100644
index 00000000..a1b83f0b
--- /dev/null
+++ b/docs/tools/editing-tools.mdx
@@ -0,0 +1,17 @@
+# Editing tools
+
+You can edit any custom use cases and tools that you create, as well as add new use cases to some of the ready made tools that Superface offers.
+
+## How to edit a use case
+
+To edit any use cases that you have created head to the [Authoring Hub](https://pod.superface.ai/authoring) in Superface.
+
+There you will see a list of any use cases you have previously created as well as the prompt used to create them.
+
+
+
+Click on the name of the use case you want to edit to open it:
+
+
+
+What you edit depends on the issue you have.
diff --git a/docs/tools/index.mdx b/docs/tools/index.mdx
index 8d634f27..773112f9 100644
--- a/docs/tools/index.mdx
+++ b/docs/tools/index.mdx
@@ -7,8 +7,6 @@ Tools sit at the heart of Superface. They connect you to the APIs of the platfor
There are two types of tools:
1. Pre-built tools provided by Superface.
-2. Tools that you can develop yourself.
-
-In this guide we will look at adding and managing the tools provided by Superface.
+2. Tools that you can [develop yourself](./tools/create-tools)
diff --git a/sidebars.js b/sidebars.js
index cb3452b7..77fbf8ce 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -119,6 +119,7 @@ module.exports = {
items: [
'tools/adding-tools',
'tools/create-tools',
+ 'tools/editing-tools',
{
type: 'category',
label: 'Tools',
diff --git a/static/img/tools/authoring-authored-use-cases.png b/static/img/tools/authoring-authored-use-cases.png
new file mode 100644
index 00000000..5839b979
Binary files /dev/null and b/static/img/tools/authoring-authored-use-cases.png differ
diff --git a/static/img/tools/authoring-check-provider.png b/static/img/tools/authoring-check-provider.png
new file mode 100644
index 00000000..4608a9c4
Binary files /dev/null and b/static/img/tools/authoring-check-provider.png differ
diff --git a/static/img/tools/authoring-config-add-custom-use-case.png b/static/img/tools/authoring-config-add-custom-use-case.png
new file mode 100644
index 00000000..4555ad41
Binary files /dev/null and b/static/img/tools/authoring-config-add-custom-use-case.png differ
diff --git a/static/img/tools/authoring-config-missing.png b/static/img/tools/authoring-config-missing.png
new file mode 100644
index 00000000..45c1484f
Binary files /dev/null and b/static/img/tools/authoring-config-missing.png differ
diff --git a/static/img/tools/authoring-custom-use-case-allowed.png b/static/img/tools/authoring-custom-use-case-allowed.png
new file mode 100644
index 00000000..8d5aad2c
Binary files /dev/null and b/static/img/tools/authoring-custom-use-case-allowed.png differ
diff --git a/static/img/tools/authoring-files-to-be-installed.png b/static/img/tools/authoring-files-to-be-installed.png
new file mode 100644
index 00000000..c1b1ac76
Binary files /dev/null and b/static/img/tools/authoring-files-to-be-installed.png differ
diff --git a/static/img/tools/authoring-index.png b/static/img/tools/authoring-index.png
new file mode 100644
index 00000000..4134b355
Binary files /dev/null and b/static/img/tools/authoring-index.png differ
diff --git a/static/img/tools/authoring-install-first.png b/static/img/tools/authoring-install-first.png
new file mode 100644
index 00000000..7f74ff30
Binary files /dev/null and b/static/img/tools/authoring-install-first.png differ
diff --git a/static/img/tools/authoring-profile-test.png b/static/img/tools/authoring-profile-test.png
new file mode 100644
index 00000000..b4210a45
Binary files /dev/null and b/static/img/tools/authoring-profile-test.png differ
diff --git a/static/img/tools/authoring-prompt-example.png b/static/img/tools/authoring-prompt-example.png
new file mode 100644
index 00000000..caac219d
Binary files /dev/null and b/static/img/tools/authoring-prompt-example.png differ
diff --git a/static/img/tools/authoring-provider-input.png b/static/img/tools/authoring-provider-input.png
new file mode 100644
index 00000000..72bcaec3
Binary files /dev/null and b/static/img/tools/authoring-provider-input.png differ
diff --git a/static/img/tools/authoring-working-on-use-case.png b/static/img/tools/authoring-working-on-use-case.png
new file mode 100644
index 00000000..b9690ec5
Binary files /dev/null and b/static/img/tools/authoring-working-on-use-case.png differ