# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Google Dialogflow Tools API
  version: 1.0.0
extends: openapi/google-dialogflow-tools-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 10
- target: $.paths['/v3/projects/{projectsId}/locations/{locationsId}/agents/{agentsId}/tools/{toolsId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a tool on a CX agent
      effect: read
      questions:
      - What OpenAPI spec or function definition backs a tool on my Dialogflow CX agent?
      - Can I view one agent tool's configuration by ID?
      instructions:
      - text: Get tool {tool} on CX agent {agent} in project {project}, location {location}.
        slots:
          tool: path.toolsId
          agent: path.agentsId
          project: path.projectsId
          location: path.locationsId
      - text: Show the definition of agent tool {tool} on {agent}.
        slots:
          tool: path.toolsId
          agent: path.agentsId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/projects/{projectsId}/locations/{locationsId}/agents/{agentsId}/tools/{toolsId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a tool from a CX agent
      effect: destructive
      questions:
      - Can I delete a tool from my CX agent even if playbooks still reference it?
      - Is a forced removal needed for an agent tool that is in use?
      instructions:
      - text: Delete tool {tool} from CX agent {agent} in project {project}, location {location}.
        slots:
          tool: path.toolsId
          agent: path.agentsId
          project: path.projectsId
          location: path.locationsId
      - text: Force-remove agent tool {tool} from {agent} with force={force}.
        slots:
          tool: path.toolsId
          agent: path.agentsId
          force: query.force
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/projects/{projectsId}/locations/{locationsId}/agents/{agentsId}/tools/{toolsId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a tool on a CX agent
      effect: write
      questions:
      - How do I swap the OpenAPI spec behind an existing CX agent tool?
      - Can I change just an agent tool's description so playbooks pick it more reliably?
      instructions:
      - text: Update tool {tool} on CX agent {agent} in project {project}, location {location} with OpenAPI spec {openapi_spec}.
        slots:
          tool: path.toolsId
          agent: path.agentsId
          project: path.projectsId
          location: path.locationsId
          openapi_spec: requestBody.openApiSpec
      - text: Change the description of agent tool {tool} to {description}.
        slots:
          tool: path.toolsId
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/projects/{projectsId}/locations/{locationsId}/agents/{agentsId}/tools'].get
  update:
    x-apievangelist-phrasing:
      intent: List tools on a CX agent
      effect: read
      questions:
      - Which tools can my CX agent's playbooks call?
      - Can I page through the tools registered on a conversational agent?
      instructions:
      - text: List the tools on CX agent {agent} in project {project}, location {location}.
        slots:
          agent: path.agentsId
          project: path.projectsId
          location: path.locationsId
      - text: Show {page_size} agent tools at a time for {agent}.
        slots:
          page_size: query.pageSize
          agent: path.agentsId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v3/projects/{projectsId}/locations/{locationsId}/agents/{agentsId}/tools'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a tool to a CX agent
      effect: write
      questions:
      - How do I give my CX agent a tool that calls my own REST API?
      - Can an agent tool be backed by a data store instead of an OpenAPI spec?
      instructions:
      - text: Create tool {display_name} on CX agent {agent} in project {project}, location {location} from OpenAPI spec {openapi_spec}.
        slots:
          display_name: requestBody.displayName
          agent: path.agentsId
          project: path.projectsId
          location: path.locationsId
          openapi_spec: requestBody.openApiSpec
      - text: Add a data store tool {display_name} to agent {agent} using spec {data_store_spec}.
        slots:
          display_name: requestBody.displayName
          agent: path.agentsId
          data_store_spec: requestBody.dataStoreSpec
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/tools'].get
  update:
    x-apievangelist-phrasing:
      intent: List ES tools in a location
      effect: read
      questions:
      - Which v2 tools are defined in my project for a given location?
      - Can I list location-level tools that aren't attached to a CX agent?
      instructions:
      - text: List v2 tools in project {project}, location {location}.
        slots:
          project: path.projectsId
          location: path.locationsId
      - text: Show location-level tools in {location}, {page_size} per page.
        slots:
          location: path.locationsId
          page_size: query.pageSize
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/tools'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an ES tool in a location
      effect: write
      questions:
      - How do I register a connector or extension tool at the project location level?
      - Can a location-level tool require the user to confirm before an action runs?
      instructions:
      - text: Create v2 tool {tool_id} named {display_name} in project {project}, location {location}.
        slots:
          tool_id: query.toolId
          display_name: requestBody.displayName
          project: path.projectsId
          location: path.locationsId
      - text: Add a location-level connector tool {display_name} in {location} with connector spec {connector_spec}.
        slots:
          display_name: requestBody.displayName
          location: path.locationsId
          connector_spec: requestBody.connectorSpec
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/tools/{toolsId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve an ES tool in a location
      effect: read
      questions:
      - What does a location-level v2 tool's tool key and spec look like?
      - Can I fetch one project location tool by ID?
      instructions:
      - text: Get v2 tool {tool} in project {project}, location {location}.
        slots:
          tool: path.toolsId
          project: path.projectsId
          location: path.locationsId
      - text: Show location-level tool {tool} in {location}.
        slots:
          tool: path.toolsId
          location: path.locationsId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/tools/{toolsId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an ES tool in a location
      effect: destructive
      questions:
      - Can I delete a location-level v2 tool I no longer need?
      - Is a project location tool removed by its ID alone?
      instructions:
      - text: Delete v2 tool {tool} in project {project}, location {location}.
        slots:
          tool: path.toolsId
          project: path.projectsId
          location: path.locationsId
      - text: Remove location-level tool {tool} from {location}.
        slots:
          tool: path.toolsId
          location: path.locationsId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/tools/{toolsId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an ES tool in a location
      effect: write
      questions:
      - How do I change the action confirmation requirement on a location-level tool?
      - Can I update a v2 tool's extension spec without recreating it?
      instructions:
      - text: Update v2 tool {tool} in project {project}, location {location} with confirmation requirement {confirmation}.
        slots:
          tool: path.toolsId
          project: path.projectsId
          location: path.locationsId
          confirmation: requestBody.actionConfirmationRequirement
      - text: Rename location-level tool {tool} in {location} to {display_name}.
        slots:
          tool: path.toolsId
          location: path.locationsId
          display_name: requestBody.displayName
      method: generated
      generated: '2026-10-01'