> ## Documentation Index
> Fetch the complete documentation index at: https://docs.potpie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools Reference

**Custom agents** access specialized tools across six categories: **Knowledge Graph**, **Code Access**, **External**, **Project Management**, **Integration**, and **Code Changes**. Assign tools per task at agent creation to control what the agent can access during execution.

## Tool Categories

| Category                                        | Description                                                                                                       |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| [Knowledge Graph](#knowledge-graph-tools)       | Query and traverse the codebase by node, tag, name, or semantic meaning                                           |
| [Code Access](#code-access-tools)               | Retrieve file contents, directory structures, and analyzed code element breakdowns                                |
| [External](#external-tools)                     | Search the web and extract content from external URLs                                                             |
| [Project Management](#project-management-tools) | Track tasks, requirements, and manage session-based workflows                                                     |
| [Integration](#integration-tools)               | Connect with external services like GitHub, Jira, Linear, and Confluence                                          |
| [Code Changes](#code-changes-management-tools)  | Manage code modifications through a session-based change tracking system. Available exclusively to the Code Agent |

## Knowledge Graph Tools

Query and traverse the [knowledge graph](/concepts/knowledge-graph) by node name, ID, tag, or semantic meaning. These tools identify relevant nodes and map the relationships between them.

<AccordionGroup>
  <Accordion title="Semantic Search">
    `ask_knowledge_graph_queries`

    Execute natural language queries against the [knowledge graph](/concepts/knowledge-graph) using **vector similarity search** over docstring [embeddings](/concepts/inference). The primary tool for semantic codebase search.

    **Parameters:**

    * `query` (string, required): Natural language or structured query
    * `project_id` (string, required): Project to query

    **Returns:** Matching nodes, relationships, and relevance scores
  </Accordion>

  <Accordion title="Fuzzy Lookup">
    `get_code_from_probable_node_name`

    Search for nodes using a probable name match. Use when the exact node name is unknown. Accepts `file_path:function_name` or `file_path:class_name` format.

    **Parameters:**

    * `name` (string, required): Probable node name to search for
    * `project_id` (string, required): Project to search within

    **Returns:** Code content and metadata for matching nodes
  </Accordion>

  <Accordion title="Exact Lookup">
    `get_code_from_node_name`

    Retrieve code using the exact node name.

    **Parameters:**

    * `name` (string, required): Exact node name
    * `project_id` (string, required): Project to search within

    **Returns:** Code content and node metadata
  </Accordion>

  <Accordion title="Node Fetch">
    `get_code_from_node_id`

    Fetch the exact code content for a specific node ID.

    **Parameters:**

    * `node_id` (string, required): The exact node ID to retrieve

    **Returns:** Complete code content, file path, and node metadata
  </Accordion>

  <Accordion title="Bulk Fetch">
    `get_code_from_multiple_node_ids`

    Retrieve code from multiple node IDs in a single request.

    **Parameters:**

    * `node_ids` (string\[], required): Array of node IDs to retrieve

    **Returns:** Array of code contents and metadata for each node
  </Accordion>

  <Accordion title="Tag Filter">
    `get_nodes_from_tags`

    Retrieve all code nodes matching one or more specified tags or labels.

    **Parameters:**

    * `tags` (string\[], required): Tags to filter by
    * `project_id` (string, required): Project to search within

    **Returns:** All nodes matching the specified tags
  </Accordion>

  <Accordion title="Graph by ID">
    `get_code_graph_from_node_id`

    Retrieve the dependency graph for a specific node by its ID. Works best with Python, JavaScript, and TypeScript repositories.

    **Parameters:**

    * `node_id` (string, required): Node ID to retrieve the graph for

    **Returns:** Dependency graph with related nodes and edge types
  </Accordion>

  <Accordion title="Graph by Name">
    `get_code_graph_from_node_name`

    Retrieve the dependency graph for a node by its name. Works best with `.py`, `.js`, and `.ts` files.

    **Parameters:**

    * `name` (string, required): Node name to retrieve the graph for
    * `project_id` (string, required): Project to search within

    **Returns:** Dependency graph with related nodes and edge types
  </Accordion>

  <Accordion title="Node Neighbors">
    `get_node_neighbours_from_node_id`

    Retrieve the immediate neighboring nodes in the [knowledge graph](/concepts/knowledge-graph) for a given node ID.

    **Parameters:**

    * `node_id` (string, required): Node ID to retrieve neighbors for

    **Returns:** List of neighboring nodes with relationship types
  </Accordion>

  <Accordion title="Smart Graph">
    `intelligent_code_graph`

    Generate a filtered, context-aware code graph. Useful for reducing graph size in larger codebases while preserving the most relevant relationships.

    **Parameters:**

    * `node_id` (string, required): Starting node for the graph
    * `project_id` (string, required): Project to query

    **Returns:** Filtered dependency graph optimized for context relevance
  </Accordion>
</AccordionGroup>

## Code Access Tools

Retrieve file contents, directory structures, and structured code element breakdowns.

<AccordionGroup>
  <Accordion title="File Structure">
    `get_code_file_structure`

    Retrieve the complete directory structure and file organization of a project.

    **Parameters:**

    * `project_id` (string, required): Project to retrieve structure for
    * `path` (string, optional): Specific path to retrieve (returns full tree if omitted)

    **Returns:** Hierarchical file and directory structure
  </Accordion>

  <Accordion title="Fetch File">
    `fetch_file`

    Read file contents with line numbers.

    **Parameters:**

    * `file_path` (string, required): Path to the file
    * `project_id` (string, required): Project containing the file

    **Returns:** File contents with line numbers
  </Accordion>

  <Accordion title="Code Analysis">
    `analyze_code_structure`

    Extract classes, functions, imports, and structural elements from a file.

    **Parameters:**

    * `file_path` (string, required): File to analyze
    * `project_id` (string, required): Project containing the file

    **Returns:** Structured representation of all code elements in the file
  </Accordion>
</AccordionGroup>

## Code Changes Management Tools

Available exclusively to the **Code Agent**. A **Redis-backed session** tracks all modifications with a 24-hour expiration. Export changes before the session expires.

<AccordionGroup>
  <Accordion title="Add File">
    `add_file_to_changes`

    Create a new file in the current session.

    **Parameters:**

    * `file_path` (string, required): Path for the new file
    * `content` (string, required): File content

    **Returns:** Confirmation with file path
  </Accordion>

  <Accordion title="Update File">
    `update_file_in_changes`

    Replace the entire content of an existing file in the session.

    **Parameters:**

    * `file_path` (string, required): File to update
    * `new_content` (string, required): Replacement content

    **Returns:** Update confirmation
  </Accordion>

  <Accordion title="Delete File">
    `delete_file_in_changes`

    Mark a file for deletion in the current session.

    **Parameters:**

    * `file_path` (string, required): File to delete

    **Returns:** Deletion confirmation
  </Accordion>

  <Accordion title="Update Lines">
    `update_file_lines`

    Modify a specific line range within a file.

    **Parameters:**

    * `file_path` (string, required): File to modify
    * `start_line` (integer, required): First line of the range
    * `end_line` (integer, required): Last line of the range
    * `new_content` (string, required): Replacement content

    **Returns:** Update confirmation
  </Accordion>

  <Accordion title="Find Replace">
    `replace_in_file`

    Find and replace text within a file, with regex support.

    **Parameters:**

    * `file_path` (string, required): File to search in
    * `pattern` (string, required): Search pattern (supports regex)
    * `replacement` (string, required): Replacement text

    **Returns:** Count of replacements made
  </Accordion>

  <Accordion title="Insert Lines">
    `insert_lines`

    Insert lines at a specific position within a file.

    **Parameters:**

    * `file_path` (string, required): File to modify
    * `line_number` (integer, required): Position to insert at
    * `content` (string, required): Content to insert

    **Returns:** Insertion confirmation
  </Accordion>

  <Accordion title="Delete Lines">
    `delete_lines`

    Remove a specific line range from a file.

    **Parameters:**

    * `file_path` (string, required): File to modify
    * `start_line` (integer, required): First line to delete
    * `end_line` (integer, required): Last line to delete

    **Returns:** Deletion confirmation
  </Accordion>

  <Accordion title="Get File">
    `get_file_from_changes`

    Retrieve the current content of a file from the session, including all pending changes.

    **Parameters:**

    * `file_path` (string, required): File to retrieve

    **Returns:** Current file content with all pending changes applied
  </Accordion>

  <Accordion title="List Files">
    `list_files_in_changes`

    List all files modified in the current session.

    **Returns:** List of file paths with their change types (added, modified, deleted)
  </Accordion>

  <Accordion title="Search Changes">
    `search_content_in_changes`

    Search across all modified files in the session.

    **Parameters:**

    * `query` (string, required): Search query
    * `regex` (boolean, optional): Enable regex matching

    **Returns:** Matching results with file paths and line numbers
  </Accordion>

  <Accordion title="Revert File">
    `clear_file_from_changes`

    Revert all pending changes for a specific file.

    **Parameters:**

    * `file_path` (string, required): File to revert

    **Returns:** Revert confirmation
  </Accordion>

  <Accordion title="Clear Session">
    `clear_all_changes`

    Discard all changes tracked in the current session.

    **Returns:** Clear confirmation
  </Accordion>

  <Accordion title="Changes Summary">
    `get_changes_summary`

    Get an overview of all modifications tracked in the current session.

    **Returns:** Summary including file count, line changes, and change types
  </Accordion>

  <Accordion title="PR Changes">
    `get_changes_for_pr`

    Retrieve a summary of all code changes for a given conversation. Used in delegated PR flows to verify changes exist in the session before calling `create_pr_workflow`.

    **Parameters:**

    * `conversation_id` (string, required): Conversation ID where changes are stored

    **Returns:** List of changed files with change types and counts
  </Accordion>

  <Accordion title="Export Changes">
    `export_changes`

    Generate a patch file or changeset for applying all session modifications.

    **Parameters:**

    * `format` (string, default: `dict`): Export format: `dict`, `list`, `json`, or `diff`

    **Returns:** Formatted changeset ready for application
  </Accordion>

  <Accordion title="Preview File">
    `show_updated_file`

    View a file with all pending changes applied.

    **Parameters:**

    * `file_path` (string, required): File to view

    **Returns:** Complete file content with all changes applied
  </Accordion>

  <Accordion title="Show Diff">
    `show_diff`

    Display a unified diff of pending changes in the session.

    **Parameters:**

    * `file_path` (string, optional): Specific file to diff. Shows all pending changes if omitted.

    **Returns:** Unified diff output
  </Accordion>

  <Accordion title="File Diff">
    `get_file_diff`

    Get a line-by-line diff for a specific file.

    **Parameters:**

    * `file_path` (string, required): File to diff

    **Returns:** Line-by-line diff for the specified file
  </Accordion>

  <Accordion title="Session Info">
    `get_session_metadata`

    Retrieve session information and statistics.

    **Returns:** Session ID, conversation ID, file count, and created/updated timestamps. All session data expires after 24 hours.
  </Accordion>
</AccordionGroup>

## External Tools

Search the web and extract content from external URLs to supplement codebase knowledge with external documentation and resources.

<AccordionGroup>
  <Accordion title="Web Search">
    `web_search_tool`

    Search external documentation, resources, and references.

    **Parameters:**

    * `query` (string, required): Search query
    * `num_results` (integer, default: `5`): Number of results to return

    **Returns:** Search results with titles, URLs, and snippets
  </Accordion>

  <Accordion title="Page Extractor">
    `webpage_extractor`

    Extract text content from a specific URL.

    **Parameters:**

    * `url` (string, required): URL to extract content from

    **Returns:** Extracted text content and page metadata
  </Accordion>

  <Accordion title="Shell Command">
    `bash_command`

    Execute read-only shell commands. Available only when the repository manager is active in the deployment. Agents cannot run commands that modify files or perform destructive operations.

    **Parameters:**

    * `command` (string, required): Shell command to execute

    **Returns:** Command output

    **Permitted use cases:** `git status`, directory listings, system information queries, read-only diagnostics.
  </Accordion>
</AccordionGroup>

## Project Management Tools

Track tasks, requirements, and manage session-based workflows for complex multi-step agent operations.

<AccordionGroup>
  <Accordion title="Create Todo">
    `add_todo`

    Create a todo item to track work in the current session.

    **Parameters:**

    * `title` (string, required): Title of the todo item
    * `description` (string, optional): Additional detail about the task

    **Returns:** Todo ID and creation confirmation
  </Accordion>

  <Accordion title="Update Status">
    `update_todo_status`

    Update the completion status of an existing todo item.

    **Parameters:**

    * `todo_id` (string, required): ID of the todo to update
    * `status` (string, required): New status: `pending`, `in_progress`, or `done`

    **Returns:** Updated todo with new status
  </Accordion>

  <Accordion title="Get Todo">
    `get_todo`

    Retrieve a specific todo item by ID.

    **Parameters:**

    * `todo_id` (string, required): ID of the todo to retrieve

    **Returns:** Todo details including title, description, status, and notes
  </Accordion>

  <Accordion title="List Todos">
    `read_todos`

    List all todo items tracked in the current session.

    **Returns:** All todo items with their statuses and notes
  </Accordion>

  <Accordion title="Add Note">
    `add_todo_note`

    Append a note to an existing todo item.

    **Parameters:**

    * `todo_id` (string, required): ID of the todo to update
    * `note` (string, required): Note content to append

    **Returns:** Updated todo with the new note
  </Accordion>

  <Accordion title="Todo Summary">
    `get_todo_summary`

    Get an overview of all todo items and their statuses in the current session.

    **Returns:** Todo counts by status and a summary of pending and completed work
  </Accordion>

  <Accordion title="Add Requirements">
    `add_requirements`

    Store requirements or constraints for the current agent session.

    **Parameters:**

    * `requirements` (string, required): Requirements content to store

    **Returns:** Confirmation of stored requirements
  </Accordion>

  <Accordion title="Get Requirements">
    `get_requirements`

    Retrieve requirements from the current session.

    **Returns:** Stored requirements content
  </Accordion>

  <Accordion title="Delete Requirements">
    `delete_requirements`

    Remove requirements from the current session. Available exclusively to the **Code Agent**.

    **Returns:** Deletion confirmation
  </Accordion>
</AccordionGroup>

## Integration Tools

Connect with external services like GitHub, Jira, Linear, and Confluence to extend agent capabilities beyond the codebase.

### GitHub Tools

<AccordionGroup>
  <Accordion title="Issue Fetcher" id="github-issue-fetcher">
    `github_tool`

    Fetch GitHub issues and pull requests with full details including diffs.

    **Parameters:**

    * `repo` (string, required): Repository in `owner/repo` format
    * `issue_or_pr_number` (integer, required): Issue or PR number to fetch

    **Returns:** Title, description, status, assignee, labels, and diff (for PRs)
  </Accordion>

  <Accordion title="File Reader" id="github-file-reader">
    `code_provider_tool`

    Read file contents from a repository.

    **Parameters:**

    * `repo` (string, required): Repository in `owner/repo` format
    * `file_path` (string, required): Path to the file

    **Returns:** File contents
  </Accordion>

  <Accordion title="Branch Creator" id="github-branch-creator">
    `code_provider_create_branch`

    Create a new branch from an existing branch or commit.

    **Parameters:**

    * `repo` (string, required): Repository in `owner/repo` format
    * `branch_name` (string, required): Name for the new branch
    * `source_branch` (string, required): Branch or commit to create from

    **Returns:** Branch creation confirmation
  </Accordion>

  <Accordion title="File Committer" id="github-file-committer">
    `code_provider_update_file`

    Modify file contents and commit the change.

    **Parameters:**

    * `repo` (string, required): Repository in `owner/repo` format
    * `file_path` (string, required): Path to the file
    * `content` (string, required): New file content
    * `commit_message` (string, required): Commit message

    **Returns:** Commit SHA and update confirmation
  </Accordion>

  <Accordion title="PR Creator" id="github-pr-creator">
    `code_provider_create_pr`

    Create a pull request with a title, description, and reviewers.

    **Parameters:**

    * `repo` (string, required): Repository in `owner/repo` format
    * `title` (string, required): PR title
    * `head` (string, required): Source branch
    * `base` (string, required): Target branch
    * `body` (string, optional): PR description

    **Returns:** PR URL and number
  </Accordion>

  <Accordion title="PR Commenter" id="github-pr-commenter">
    `code_provider_add_pr_comment`

    Add a comment to a pull request or a specific line within it.

    **Parameters:**

    * `repo` (string, required): Repository in `owner/repo` format
    * `pr_number` (integer, required): PR number
    * `body` (string, required): Comment content
    * `file_path` (string, optional): File path for inline comment
    * `line` (integer, optional): Line number for inline comment

    **Returns:** Comment URL and ID
  </Accordion>
</AccordionGroup>

### Linear Tools

<AccordionGroup>
  <Accordion title="Issue Fetcher" id="linear-issue-fetcher">
    `get_linear_issue`

    Fetch detailed information about a Linear issue.

    **Parameters:**

    * `issue_id` (string, required): Issue ID or key (e.g. `ABC-123`)

    **Returns:** Title, description, status, assignee, team, priority, URL, and timestamps
  </Accordion>

  <Accordion title="Issue Updater" id="linear-issue-updater">
    `update_linear_issue`

    Update properties of a Linear issue.

    **Parameters:**

    * `issue_id` (string, required): Issue ID or key
    * `input` (object, required): Fields to update — title, description, status, priority, assignee, team, or labels

    **Returns:** Updated issue confirmation
  </Accordion>
</AccordionGroup>

### Jira Tools

<AccordionGroup>
  <Accordion title="Issue Creator" id="jira-issue-creator">
    `create_jira_issue_tool`

    Create a new Jira issue in a project.

    **Parameters:**

    * `project_key` (string, required): Project key (e.g. `ENG`)
    * `summary` (string, required): Issue title
    * `description` (string, optional): Issue description
    * `issue_type` (string, optional): Issue type (Bug, Task, Story)
    * `priority` (string, optional): Priority level

    **Returns:** Issue key and URL
  </Accordion>

  <Accordion title="Issue Fetcher" id="jira-issue-fetcher">
    `get_jira_issue_tool`

    Fetch details for a Jira issue.

    **Parameters:**

    * `issue_key` (string, required): Issue key (e.g. `ENG-123`)

    **Returns:** Title, description, status, assignee, priority, comments, and attachments
  </Accordion>

  <Accordion title="Issue Updater" id="jira-issue-updater">
    `update_jira_issue_tool`

    Update fields on a Jira issue.

    **Parameters:**

    * `issue_key` (string, required): Issue key
    * `fields` (object, required): Fields to update — description, assignee, priority, etc.

    **Returns:** Update confirmation
  </Accordion>

  <Accordion title="Issue Search" id="jira-issue-search">
    `search_jira_issues_tool`

    Search Jira issues using JQL.

    **Parameters:**

    * `jql` (string, required): JQL query string
    * `max_results` (integer, optional): Maximum results to return

    **Returns:** Matching issues with key, title, status, and assignee
  </Accordion>

  <Accordion title="Comment Writer" id="jira-comment-writer">
    `add_jira_comment_tool`

    Add a comment to a Jira issue.

    **Parameters:**

    * `issue_key` (string, required): Issue key
    * `body` (string, required): Comment content

    **Returns:** Comment ID and URL
  </Accordion>

  <Accordion title="Status Mover" id="jira-status-mover">
    `transition_jira_issue_tool`

    Move a Jira issue to a new status.

    **Parameters:**

    * `issue_key` (string, required): Issue key
    * `transition` (string, required): Target status name (e.g. `In Progress`, `Done`)

    **Returns:** Transition confirmation
  </Accordion>

  <Accordion title="Issue Linker" id="jira-issue-linker">
    `link_jira_issues_tool`

    Create a link between two Jira issues.

    **Parameters:**

    * `inward_issue` (string, required): Source issue key
    * `outward_issue` (string, required): Target issue key
    * `link_type` (string, required): Link type — blocks, relates to, duplicates, clones

    **Returns:** Link creation confirmation
  </Accordion>

  <Accordion title="Project Lister" id="jira-project-lister">
    `get_jira_projects_tool`

    List all accessible Jira projects.

    **Returns:** Project keys, names, and types
  </Accordion>

  <Accordion title="Project Details" id="jira-project-details">
    `get_jira_project_details_tool`

    Get metadata for a specific Jira project.

    **Parameters:**

    * `project_key` (string, required): Project key

    **Returns:** Project name, description, lead, issue types, and statuses
  </Accordion>

  <Accordion title="Project Members" id="jira-project-members">
    `get_jira_project_users_tool`

    List members of a Jira project.

    **Parameters:**

    * `project_key` (string, required): Project key

    **Returns:** User list with names and account IDs
  </Accordion>
</AccordionGroup>

### Confluence Tools

<AccordionGroup>
  <Accordion title="Space Lister" id="confluence-space-lister">
    `get_confluence_spaces_tool`

    List all accessible Confluence spaces.

    **Returns:** Space keys, names, and types (global/personal)
  </Accordion>

  <Accordion title="Page Fetcher" id="confluence-page-fetcher">
    `get_confluence_page_tool`

    Retrieve a Confluence page by ID.

    **Parameters:**

    * `page_id` (string, required): Confluence page ID

    **Returns:** Title, body content, version, space, and creator
  </Accordion>

  <Accordion title="Space Pages" id="confluence-space-pages">
    `get_confluence_space_pages_tool`

    List all pages in a Confluence space.

    **Parameters:**

    * `space_key` (string, required): Space key (e.g. `DOCS`)

    **Returns:** Page list with titles, IDs, and creation dates
  </Accordion>

  <Accordion title="Page Search" id="confluence-page-search">
    `search_confluence_pages_tool`

    Search Confluence content using CQL.

    **Parameters:**

    * `cql` (string, required): CQL query string
    * `limit` (integer, optional): Maximum results to return

    **Returns:** Matching pages with title, space, and excerpt
  </Accordion>

  <Accordion title="Page Creator" id="confluence-page-creator">
    `create_confluence_page_tool`

    Create a new Confluence page.

    **Parameters:**

    * `space_key` (string, required): Space to create the page in
    * `title` (string, required): Page title
    * `content` (string, required): Page content (Markdown auto-converted to storage format)
    * `parent_id` (string, optional): Parent page ID

    **Returns:** Page ID and URL
  </Accordion>

  <Accordion title="Page Updater" id="confluence-page-updater">
    `update_confluence_page_tool`

    Update an existing Confluence page. Automatically increments version number.

    **Parameters:**

    * `page_id` (string, required): Page ID to update
    * `title` (string, optional): New title
    * `content` (string, optional): New content

    **Returns:** Update confirmation with new version number
  </Accordion>

  <Accordion title="Comment Writer" id="confluence-comment-writer">
    `add_confluence_comment_tool`

    Add a comment to a Confluence page.

    **Parameters:**

    * `page_id` (string, required): Page ID
    * `body` (string, required): Comment content

    **Returns:** Comment ID and confirmation
  </Accordion>
</AccordionGroup>

### Change Detection

<AccordionGroup>
  <Accordion title="Change Detection">
    `change_detection`

    Detect code changes in the current branch compared to the default branch and retrieve updated function details.

    **Parameters:**

    * `base_branch` (string, default: `main`): Branch to compare against
    * `target_branch` (string, optional): Branch or commit to compare (defaults to current)
    * `project_id` (string, required): Project to analyze

    **Returns:** Changed files with diff information and impact analysis
  </Accordion>
</AccordionGroup>