Elastic Stack · OpenAPI Overlay 1.0.0

API Evangelist conversational phrasing for Kibana agent builder API

42 actions 42 updates phrasing extends openapi/elk-stack-agent-builder-api-openapi.yml
Generated by API Evangelist Written by API Evangelist tooling for Elastic Stack's API. It is a proposal applied on top of the contract, not a document Elastic Stack publishes.
View Overlay File View on GitHub Overlay Specification

What the actions change

x-apievangelist-phrasing

Targets 42 · first 16 shown; the file carries all of them

$.info
$.paths['/api/agent_builder/a2a/{agentId}'].post
$.paths['/api/agent_builder/a2a/{agentId}.json'].get
$.paths['/api/agent_builder/agents'].get
$.paths['/api/agent_builder/agents'].post
$.paths['/api/agent_builder/agents/{agent_id}/consumption'].post
$.paths['/api/agent_builder/agents/{id}'].get
$.paths['/api/agent_builder/agents/{id}'].put
$.paths['/api/agent_builder/agents/{id}'].delete
$.paths['/api/agent_builder/agents/{id}/access_control'].get
$.paths['/api/agent_builder/agents/{id}/access_control'].put
$.paths['/api/agent_builder/conversations'].get
$.paths['/api/agent_builder/conversations'].post
$.paths['/api/agent_builder/conversations/{conversation_id}'].get
$.paths['/api/agent_builder/conversations/{conversation_id}'].delete
$.paths['/api/agent_builder/conversations/{conversation_id}/access_control'].put

OpenAPI Overlay

Raw ↑
# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Kibana agent builder API
  version: 1.0.0
extends: openapi/elk-stack-agent-builder-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 41
- target: $.paths['/api/agent_builder/a2a/{agentId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Send an A2A protocol task to an agent
      effect: write
      questions:
      - Can an external A2A client hand a task to one of my Agent Builder agents?
      - What endpoint does an A2A SDK post tasks to for an Elastic agent?
      instructions:
      - text: Send an A2A task to agent {agentId} over the agent-to-agent protocol.
        slots:
          agentId: path.agentId
      - text: Point my A2A client at agent {agentId} so it can submit tasks.
        slots:
          agentId: path.agentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/a2a/{agentId}.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an agent's A2A discovery card
      effect: read
      questions:
      - Where do I find the A2A agent card that advertises an Agent Builder agent for discovery?
      - What metadata does the A2A agent card JSON expose about my agent?
      instructions:
      - text: Fetch the A2A agent card JSON for agent {agentId}.
        slots:
          agentId: path.agentId
      - text: Show the discovery metadata other A2A clients see for agent {agentId}.
        slots:
          agentId: path.agentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/agents'].get
  update:
    x-apievangelist-phrasing:
      intent: List Agent Builder agents
      effect: read
      questions:
      - Which agents are defined in my Kibana Agent Builder?
      - Can I see every agent along with the tools assigned to it?
      instructions:
      - text: List all my Agent Builder agents with their configuration.
      - text: Show every available agent and the tools each one has.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/agents'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an Agent Builder agent
      effect: write
      questions:
      - How do I create a new custom agent in Elastic Agent Builder?
      - What do I need to supply to define a new agent's behavior and tools?
      instructions:
      - text: Create a new agent with id {id} named {name}, described as {description}.
        slots:
          id: requestBody.id
          name: requestBody.name
          description: requestBody.description
      - text: Define agent {name} using configuration {configuration} and labels {labels}.
        slots:
          name: requestBody.name
          configuration: requestBody.configuration
          labels: requestBody.labels
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/agents/{agent_id}/consumption'].post
  update:
    x-apievangelist-phrasing:
      intent: Get an agent's token consumption per conversation
      effect: read
      questions:
      - How many LLM tokens has a given agent used in each conversation?
      - Can I find the conversations where an agent triggered high token usage warnings?
      - Which users are driving an agent's input and output token counts?
      instructions:
      - text: Show per-conversation token consumption for agent {agent_id}.
        slots:
          agent_id: path.agent_id
      - text: List only conversations flagged with token usage warnings for agent {agent_id}.
        slots:
          agent_id: path.agent_id
      - text: Break down agent {agent_id} token usage for users {usernames}.
        slots:
          agent_id: path.agent_id
          usernames: requestBody.usernames
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/agents/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one agent's full definition
      effect: read
      questions:
      - What configuration and tool assignments does a specific agent have?
      - Can I look up a single Agent Builder agent by its id?
      instructions:
      - text: Get the full definition of agent {id}.
        slots:
          id: path.id
      - text: Show the configuration and tools assigned to agent {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/agents/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an existing agent
      effect: write
      questions:
      - Can I change the instructions or tools of an agent I already created?
      - How do I rename an existing Agent Builder agent or change its avatar?
      instructions:
      - text: Update agent {id} with new configuration {configuration}.
        slots:
          id: path.id
          configuration: requestBody.configuration
      - text: Rename existing agent {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Change the avatar color of agent {id} to {avatar_color}.
        slots:
          id: path.id
          avatar_color: requestBody.avatar_color
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/agents/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an agent
      effect: destructive
      questions:
      - Is deleting an Agent Builder agent permanent?
      - How do I remove an agent I no longer need?
      instructions:
      - text: Delete agent {id} permanently.
        slots:
          id: path.id
      - text: Remove the Agent Builder agent {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/agents/{id}/access_control'].get
  update:
    x-apievangelist-phrasing:
      intent: View who can access an agent
      effect: read
      questions:
      - Who has access to a particular agent and at what permission level?
      - Can I check whether I'm allowed to manage an agent's access control list?
      instructions:
      - text: Show the access control list for agent {id}.
        slots:
          id: path.id
      - text: List the users and roles granted access to agent {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/agents/{id}/access_control'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace an agent's access control entries
      effect: write
      questions:
      - How do I share an agent with other users or give someone Manager rights on it?
      - Does updating an agent's access list replace all existing entries?
      instructions:
      - text: Replace the access control entries on agent {id} with {entries}.
        slots:
          id: path.id
          entries: requestBody.entries
      - text: 'Grant these users access to agent {id}: {entries}.'
        slots:
          id: path.id
          entries: requestBody.entries
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/conversations'].get
  update:
    x-apievangelist-phrasing:
      intent: List agent chat conversations
      effect: read
      questions:
      - Where can I see all my past agent chat conversations?
      - Can I filter my conversation history to just one agent?
      instructions:
      - text: List all my agent conversations.
      - text: Show only the conversations I've had with agent {agent_id}.
        slots:
          agent_id: query.agent_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/conversations'].post
  update:
    x-apievangelist-phrasing:
      intent: Start an empty conversation
      effect: write
      questions:
      - Can I get a conversation ID before sending the first chat message?
      - How do I open a blank conversation with an agent without sending anything yet?
      instructions:
      - text: Create an empty conversation with agent {agent_id} titled {title}.
        slots:
          agent_id: requestBody.agent_id
          title: requestBody.title
      - text: Open a new blank conversation and give me its ID.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/conversations/{conversation_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a conversation's full history
      effect: read
      questions:
      - How can I read back every message in one agent conversation?
      - What metadata is stored with a single conversation?
      instructions:
      - text: Get the full message history of conversation {conversation_id}.
        slots:
          conversation_id: path.conversation_id
      - text: Show conversation {conversation_id} with all its messages.
        slots:
          conversation_id: path.conversation_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/conversations/{conversation_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a conversation
      effect: destructive
      questions:
      - Can I permanently delete an agent conversation?
      - Is there a way to undo deleting a chat conversation?
      instructions:
      - text: Delete conversation {conversation_id}.
        slots:
          conversation_id: path.conversation_id
      - text: Permanently remove the chat conversation {conversation_id}.
        slots:
          conversation_id: path.conversation_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/conversations/{conversation_id}/access_control'].put
  update:
    x-apievangelist-phrasing:
      intent: Set who can see a conversation
      effect: write
      questions:
      - How do I share one of my agent conversations with teammates?
      - Who is allowed to change a conversation's access mode?
      instructions:
      - text: Set conversation {conversation_id} to access mode {access_mode} with members {entries}.
        slots:
          conversation_id: path.conversation_id
          access_mode: requestBody.access_mode
          entries: requestBody.entries
      - text: Make conversation {conversation_id} {access_mode} and remove all shared members.
        slots:
          conversation_id: path.conversation_id
          access_mode: requestBody.access_mode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/conversations/{conversation_id}/attachments'].get
  update:
    x-apievangelist-phrasing:
      intent: List a conversation's attachments
      effect: read
      questions:
      - What files or data are attached to an agent conversation?
      - Can I also see attachments that were soft-deleted from a conversation?
      instructions:
      - text: List the attachments in conversation {conversation_id}.
        slots:
          conversation_id: path.conversation_id
      - text: List all attachments in conversation {conversation_id}, including soft-deleted ones.
        slots:
          conversation_id: path.conversation_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/conversations/{conversation_id}/attachments'].post
  update:
    x-apievangelist-phrasing:
      intent: Attach data to a conversation
      effect: write
      questions:
      - How do I add an attachment to an existing agent conversation?
      - Are conversation attachments versioned when I add them?
      instructions:
      - text: Attach {data} as a {type} attachment to conversation {conversation_id}.
        slots:
          data: requestBody.data
          type: requestBody.type
          conversation_id: path.conversation_id
      - text: Add a hidden {type} attachment with {data} to conversation {conversation_id}.
        slots:
          type: requestBody.type
          data: requestBody.data
          conversation_id: path.conversation_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/conversations/{conversation_id}/attachments/{attachment_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace an attachment's content
      effect: write
      questions:
      - Does changing an attachment's content create a new version?
      - Can I edit the data inside an attachment already in a conversation?
      instructions:
      - text: Update the content of attachment {attachment_id} in conversation {conversation_id} to {data}.
        slots:
          attachment_id: path.attachment_id
          conversation_id: path.conversation_id
          data: requestBody.data
      - text: Save a new version of attachment {attachment_id} in conversation {conversation_id} with {data}.
        slots:
          attachment_id: path.attachment_id
          conversation_id: path.conversation_id
          data: requestBody.data
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/conversations/{conversation_id}/attachments/{attachment_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a conversation attachment
      effect: destructive
      questions:
      - Is removing a conversation attachment a soft delete I can undo?
      - How do I permanently purge an attachment nothing references anymore?
      instructions:
      - text: Delete attachment {attachment_id} from conversation {conversation_id}.
        slots:
          attachment_id: path.attachment_id
          conversation_id: path.conversation_id
      - text: Permanently purge unreferenced attachment {attachment_id} from conversation {conversation_id}.
        slots:
          attachment_id: path.attachment_id
          conversation_id: path.conversation_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/conversations/{conversation_id}/attachments/{attachment_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename a conversation attachment
      effect: write
      questions:
      - Can I rename an attachment without creating a new version of it?
      - Is there a way to change only an attachment's description label?
      instructions:
      - text: Rename attachment {attachment_id} in conversation {conversation_id} to {description}.
        slots:
          attachment_id: path.attachment_id
          conversation_id: path.conversation_id
          description: requestBody.description
      - text: Relabel attachment {attachment_id} in conversation {conversation_id} as {description} without versioning it.
        slots:
          attachment_id: path.attachment_id
          conversation_id: path.conversation_id
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/conversations/{conversation_id}/attachments/{attachment_id}/_restore'].post
  update:
    x-apievangelist-phrasing:
      intent: Restore a soft-deleted attachment
      effect: write
      questions:
      - Can I bring back an attachment I deleted from a conversation?
      - How do I undo a soft delete on a conversation attachment?
      instructions:
      - text: Restore deleted attachment {attachment_id} in conversation {conversation_id}.
        slots:
          attachment_id: path.attachment_id
          conversation_id: path.conversation_id
      - text: Undelete attachment {attachment_id} from conversation {conversation_id}.
        slots:
          attachment_id: path.attachment_id
          conversation_id: path.conversation_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/conversations/{conversation_id}/attachments/{attachment_id}/origin'].put
  update:
    x-apievangelist-phrasing:
      intent: Link an attachment to its saved origin
      effect: write
      questions:
      - After saving a by-value attachment, how do I link it to its persistent store?
      - Can I change the origin reference an attachment points to?
      instructions:
      - text: Set the origin of attachment {attachment_id} in conversation {conversation_id} to {origin}.
        slots:
          attachment_id: path.attachment_id
          conversation_id: path.conversation_id
          origin: requestBody.origin
      - text: Link attachment {attachment_id} in conversation {conversation_id} to its saved source {origin}.
        slots:
          attachment_id: path.attachment_id
          conversation_id: path.conversation_id
          origin: requestBody.origin
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/conversations/{conversation_id}/attachments/stale'].get
  update:
    x-apievangelist-phrasing:
      intent: Check if conversation attachments are stale
      effect: read
      questions:
      - Have any attachments in my conversation drifted from their original source?
      - Which conversation attachments are out of date compared with their origin snapshot?
      instructions:
      - text: Check which attachments in conversation {conversation_id} are stale.
        slots:
          conversation_id: path.conversation_id
      - text: Compare attachments in conversation {conversation_id} against their origin snapshots.
        slots:
          conversation_id: path.conversation_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/converse'].post
  update:
    x-apievangelist-phrasing:
      intent: Chat with an agent and wait for the answer
      effect: write
      questions:
      - How do I send a message to an Elastic agent and get back its complete reply in one response?
      - Can I continue an existing conversation by passing its ID with my next message?
      instructions:
      - text: 'Ask agent {agent_id}: {input} and wait for the full answer.'
        slots:
          agent_id: requestBody.agent_id
          input: requestBody.input
      - text: Send {input} in conversation {conversation_id} and return the final response.
        slots:
          input: requestBody.input
          conversation_id: requestBody.conversation_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/converse/async'].post
  update:
    x-apievangelist-phrasing:
      intent: Chat with an agent and stream events
      effect: write
      questions:
      - Can I watch an agent's intermediate reasoning steps stream in as it works?
      - Is there a streaming version of agent chat that sends real-time events?
      instructions:
      - text: Stream agent {agent_id}'s reply to {input} as live events.
        slots:
          agent_id: requestBody.agent_id
          input: requestBody.input
      - text: Send {input} to conversation {conversation_id} and stream the steps as they happen.
        slots:
          input: requestBody.input
          conversation_id: requestBody.conversation_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/mcp'].post
  update:
    x-apievangelist-phrasing:
      intent: Connect an MCP client to Agent Builder tools
      effect: write
      questions:
      - Can I use Agent Builder tools from an MCP client like an IDE assistant?
      - What is the MCP server endpoint Kibana exposes for Agent Builder?
      instructions:
      - text: Connect my MCP client to the Agent Builder MCP server.
      - text: Expose Agent Builder tools in namespace {namespace} over MCP.
        slots:
          namespace: query.namespace
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/plugins'].get
  update:
    x-apievangelist-phrasing:
      intent: List installed Agent Builder plugins
      effect: read
      questions:
      - Which plugins are installed in Agent Builder and what assets do they manage?
      - What skills have come in through installed plugins?
      instructions:
      - text: List all installed Agent Builder plugins.
      - text: Show every plugin and the managed assets it bundles.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/plugins/{pluginId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an installed plugin
      effect: read
      questions:
      - What does a specific installed plugin contain?
      - Can I look up one Agent Builder plugin by id?
      instructions:
      - text: Get the details of plugin {pluginId}.
        slots:
          pluginId: path.pluginId
      - text: Show what plugin {pluginId} installed.
        slots:
          pluginId: path.pluginId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/plugins/{pluginId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Uninstall a plugin
      effect: destructive
      questions:
      - How do I uninstall a plugin from Agent Builder?
      - Can I force-remove a plugin even if its assets are still in use?
      instructions:
      - text: Uninstall plugin {pluginId}.
        slots:
          pluginId: path.pluginId
      - text: Force delete plugin {pluginId}.
        slots:
          pluginId: path.pluginId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/plugins/install'].post
  update:
    x-apievangelist-phrasing:
      intent: Install a plugin from a URL
      effect: write
      questions:
      - Can I install an agent plugin straight from a GitHub URL or a ZIP file?
      - What formats does Agent Builder accept when installing a plugin?
      instructions:
      - text: Install the plugin from {url}.
        slots:
          url: requestBody.url
      - text: Install the plugin at {url} under the name {plugin_name}.
        slots:
          url: requestBody.url
          plugin_name: requestBody.plugin_name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/skills'].get
  update:
    x-apievangelist-phrasing:
      intent: List agent skills
      effect: read
      questions:
      - What skills are available to my agents, built-in and custom?
      - Can I include skills that came from installed plugins in the list?
      instructions:
      - text: List all Agent Builder skills.
      - text: List skills including those provided by plugins.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/skills'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom skill
      effect: write
      questions:
      - How do I write my own skill for Agent Builder agents?
      - Can a new skill reference specific tools?
      instructions:
      - text: Create skill {id} named {name}, described as {description}, with content {content}.
        slots:
          id: requestBody.id
          name: requestBody.name
          description: requestBody.description
          content: requestBody.content
      - text: Add a skill {name} whose content is {content} and that uses tools {tool_ids}.
        slots:
          name: requestBody.name
          content: requestBody.content
          tool_ids: requestBody.tool_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/skills/{skillId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a skill
      effect: read
      questions:
      - What content and tools does a particular skill define?
      - Can I fetch one skill by its id?
      instructions:
      - text: Get skill {skillId}.
        slots:
          skillId: path.skillId
      - text: Show the content of skill {skillId}.
        slots:
          skillId: path.skillId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/skills/{skillId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a custom skill
      effect: write
      questions:
      - Can I edit a skill I created earlier?
      - Is it possible to change the tools a user-created skill uses?
      instructions:
      - text: Update skill {skillId} with new content {content}.
        slots:
          skillId: path.skillId
          content: requestBody.content
      - text: Change the tools used by skill {skillId} to {tool_ids}.
        slots:
          skillId: path.skillId
          tool_ids: requestBody.tool_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/skills/{skillId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a custom skill
      effect: destructive
      questions:
      - What happens if I delete a skill that agents still reference?
      - Can built-in skills be deleted?
      instructions:
      - text: Delete skill {skillId}.
        slots:
          skillId: path.skillId
      - text: Force delete skill {skillId} and detach it from any agents.
        slots:
          skillId: path.skillId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/tools'].get
  update:
    x-apievangelist-phrasing:
      intent: List agent tools
      effect: read
      questions:
      - Which tools can my Agent Builder agents call?
      - Can I see each tool's schema and configuration requirements?
      instructions:
      - text: List all Agent Builder tools.
      - text: Show every available tool with its schema.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/tools'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom tool
      effect: write
      questions:
      - How do I define a custom tool for my agents to use?
      - Can I require confirmation before an agent runs a tool I create?
      instructions:
      - text: Create a {type} tool with id {tool_id} and configuration {configuration}.
        slots:
          type: requestBody.type
          tool_id: requestBody.id
          configuration: requestBody.configuration
      - text: Create tool {tool_id} of type {type}, tagged {tags}, with configuration {configuration}.
        slots:
          tool_id: requestBody.id
          type: requestBody.type
          tags: requestBody.tags
          configuration: requestBody.configuration
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/tools/_execute'].post
  update:
    x-apievangelist-phrasing:
      intent: Run a tool directly
      effect: write
      questions:
      - Can I test a tool by running it directly with my own inputs, outside a chat?
      - Is it possible to run a tool through a specific connector?
      instructions:
      - text: Run tool {tool_id} with parameters {tool_params}.
        slots:
          tool_id: requestBody.tool_id
          tool_params: requestBody.tool_params
      - text: Execute tool {tool_id} with {tool_params} using connector {connector_id}.
        slots:
          tool_id: requestBody.tool_id
          tool_params: requestBody.tool_params
          connector_id: requestBody.connector_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/tools/{toolId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a tool's definition
      effect: read
      questions:
      - What parameters and configuration does one particular tool expect?
      - Can I retrieve a single tool definition by id?
      instructions:
      - text: Get the definition of tool {toolId}.
        slots:
          toolId: path.toolId
      - text: Show the schema for tool {toolId}.
        slots:
          toolId: path.toolId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/tools/{toolId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a tool
      effect: write
      questions:
      - Can I change the configuration of a tool that already exists?
      - How do I retag or redescribe an existing tool?
      instructions:
      - text: Update tool {toolId} with configuration {configuration}.
        slots:
          toolId: path.toolId
          configuration: requestBody.configuration
      - text: Set the tags on tool {toolId} to {tags}.
        slots:
          toolId: path.toolId
          tags: requestBody.tags
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/agent_builder/tools/{toolId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a tool
      effect: destructive
      questions:
      - Is deleting a tool from Agent Builder reversible?
      - Can I force the removal of a tool agents are still using?
      instructions:
      - text: Delete tool {toolId}.
        slots:
          toolId: path.toolId
      - text: Force delete tool {toolId} even if agents use it.
        slots:
          toolId: path.toolId
      method: generated
      generated: '2026-09-26'