Skip to main content
Tools & Integrations

Tool Building Resources

Use the Tool Builder and Tool Doc Writer Mates to write the OpenAPI schema and the user guide of a custom REST API tool.

Last updated 14 days ago

Two Mates of the Mates Store help you build and document custom REST API tools: Tool Builder writes the OpenAPI schema, and Tool Doc Writer writes the user guide. This article shows how to add them to your organization and how to work with them, from the API documentation to a tool your colleagues can use.

Add the Mates to your organization

  1. In the sidebar, open Mates & tools, then Mates Store.
  2. Find Tool Builder and click Onboard. If the Mate is already in your organization, the button is View in organization and opens it. Do the same for Tool Doc Writer.

Adding a Mate from the store needs Mate-management rights: the Expert plan by default; your organization's plans may differ.

Tool Builder

Tool Builder turns API documentation into an OpenAPI 3 schema written for Mates. It helps you:

  • read the API documentation and pick the endpoints you need,
  • write the schema with clear operation IDs, parameter descriptions and ## For LLMs guidance,
  • find and fix errors in an existing schema,
  • decide which values are credentials and how to pass them.

Example request: "I need a REST API tool for the Salesforce Marketing Cloud API. Help me write the OpenAPI schema for the endpoints that list and create campaigns."

Tool Doc Writer

Once the tool works, Tool Doc Writer writes the guide that your colleagues read: what the tool does, example requests, the parameters, the credentials it needs, and its limits.

Example request: "I created a REST API tool for our internal CRM. Here is its OpenAPI schema. Write a user guide for it."

Paste the result in the Overview description of the tool, so that it shows on the tool page.

Give them web access

Tool Builder and Tool Doc Writer come without tools. Attach a web search tool or a web scraping tool from the Tool Store to let them read online API documentation by themselves: open the Mate, then the Tools tab, then Add a tool.

Build your first tool

  1. Pick the API and gather its documentation, the authentication it requires and a few example values.
  2. Write the schema with Tool Builder. Start with the two or three endpoints you need most.
  3. Create the tool: Toolbox > Connect tool > Add custom tool > Other custom tool paths > REST API. Paste the schema.
  4. Add the credentials in Advanced settings: an Auth preset, request headers, or custom parameters, each with the scope Organization (one value for everyone) or Member (each person enters their own). See "Master the REST API Tool".
  5. Click Install, then attach the tool to a test Mate in the tool attachment dialog.
  6. Test it in a conversation: a request that needs the tool, then a request that should fail.
  7. Document it with Tool Doc Writer, then attach the tool to the Mates that need it.

Start small and add endpoints once the first ones work.

Common challenges

  • Authentication. If the service signs users in with OAuth and publishes an MCP server, connect the MCP server instead of writing a REST tool: MCP tools support OAuth sign-in, per member or shared. See "Deploying a Custom MCP Server in Your Organization".
  • Large APIs. An API with hundreds of endpoints overwhelms a Mate. Declare only the endpoints you need.
  • Rate limits. Note the provider's limits in the operation descriptions, so the Mate does not repeat calls needlessly.
  • Schema errors. Paste the error and the schema to Tool Builder and ask for a fix.

Was this helpful?

Still need help? Ask the team