> For the complete documentation index, see [llms.txt](https://docs.protoboard.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.protoboard.xyz/agent-bridge/tool-reference.md).

# Tool reference

Every tool the Protoboard MCP server exposes, with what it does, whether it changes your board and where it runs

## Goal

Look up any tool your agent can call through the Agent Bridge: what it does, whether it reads or changes your board, and whether it needs an open board tab.

## How to read this page

The Protoboard MCP server exposes **88 tools**. 78 of them run inside your open board tab, so they need Protoboard open in a browser; the rest run on the Protoboard server.

| Column      | Meaning                                                                                                                                                                                                                                                                                                                           |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Access**  | **Read** never changes the board. **Write** changes the board and can be undone in the editor. **Destructive** removes something or replaces the board. **Session** changes which board or ProtoBot mode is active. **Files a request** sends a public request to the ProtoPart library team, or feedback to the Protoboard team. |
| **Runs in** | **Board tab** tools run in your browser and need the board open. A sleeping tab queues the call until you focus it. **Server** tools work without an open tab.                                                                                                                                                                    |

{% hint style="info" %}
Your agent sees the full input schema for every tool when it connects. Ask it to "list the Protoboard tools" if you want the live list. Tool calls made through the Agent Bridge don't use ProtoBot Energy.
{% endhint %}

## Connection and session

| Tool                     | What it does                                                                                             | Access  | Runs in   |
| ------------------------ | -------------------------------------------------------------------------------------------------------- | ------- | --------- |
| `list_boards`            | List Protoboard boards currently open in the browser.                                                    | Read    | Server    |
| `connect_board`          | Connect to a specific Protoboard board.                                                                  | Session | Server    |
| `open_board`             | Create a new Protoboard board (or resolve an existing one) and return a URL to open it in the browser.   | Session | Server    |
| `get_call_status`        | Check the status of a previously submitted tool call by callId.                                          | Read    | Server    |
| `review_board`           | Run a comprehensive board review: board summary, DRC, layout issues, plan status, and BOM cost estimate. | Read    | Server    |
| `switch_mode`            | Switch the current ProtoBot session to a different complexity mode (plan, concept, integrate).           | Session | Server    |
| `get_bridge_diagnostics` | Report the health of the board tab's Agent Bridge connection, for troubleshooting.                       | Read    | Board tab |

## Library and parts

| Tool                 | What it does                                                                                                                                                 | Access | Runs in   |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | --------- |
| `search_library`     | Search the remote parts library (cloud catalog) for components to import.                                                                                    | Read   | Board tab |
| `get_taxonomy`       | Browse the part library's category taxonomy (the same tree the library filter uses).                                                                         | Read   | Server    |
| `place_part`         | Place a part from the library onto the board at a specific position.                                                                                         | Write  | Board tab |
| `swap_template`      | Swap the template backing an existing part in place: same instance, same position, same nickname, same harness wiring (where the mapped interfaces survive). | Write  | Board tab |
| `create_blank_part`  | Create a blank/custom part without a template.                                                                                                               | Write  | Board tab |
| `move_part`          | Move a part to a new position on the canvas                                                                                                                  | Write  | Board tab |
| `rename_part`        | Rename a part instance (updates nickname, not template name).                                                                                                | Write  | Board tab |
| `inspect_part`       | Inspect a part (the agent's view of the part inspector).                                                                                                     | Read   | Board tab |
| `get_parts_list`     | Get a detailed parts list from the current board (ids, template ids, nicknames, positions, interface counts).                                                | Read   | Board tab |
| `duplicate_elements` | Duplicate canvas elements (parts, annotations, harnesses, note edges).                                                                                       | Write  | Board tab |

## Part templates

| Tool                            | What it does                                                                                                            | Access      | Runs in   |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------- | --------- |
| `get_template_json`             | Read a template's ProtoPart JSON.                                                                                       | Read        | Board tab |
| `update_template_json`          | Edit a board-local part template's ProtoPart JSON. Every part that uses the template on this board picks up the change. | Write       | Board tab |
| `set_template_icon`             | Set (or clear) a template's canvas icon and color.                                                                      | Write       | Board tab |
| `check_project_part_updates`    | Check whether any parts already in the current project have a newer, verified version available in the remote library.  | Read        | Board tab |
| `add_template_artifact`         | Attach a link or pre-uploaded file reference to a part template (board-local).                                          | Write       | Board tab |
| `remove_template_artifact`      | Remove an artifact from a part template's artifact list.                                                                | Destructive | Board tab |
| `set_template_preview_artifact` | Pin one of the template's image artifacts as the preview thumbnail (or clear the override with null).                   | Write       | Board tab |

## Interfaces

| Tool                        | What it does                                                                   | Access      | Runs in   |
| --------------------------- | ------------------------------------------------------------------------------ | ----------- | --------- |
| `list_interface_instances`  | List interface instances on a part (ids, definition ids, names)                | Read        | Board tab |
| `list_interface_functions`  | List functions for a specific interface instance (derived from its definition) | Read        | Board tab |
| `add_interface_instance`    | Add an interface instance to a part, up to the interface's capacity.           | Write       | Board tab |
| `remove_interface_instance` | Remove an interface instance from a part.                                      | Destructive | Board tab |

## Harnesses and function links

| Tool                     | What it does                                                                                                                                                                     | Access      | Runs in   |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | --------- |
| `create_harness`         | Create a connection between two nodes.                                                                                                                                           | Write       | Board tab |
| `link_interfaces`        | Add an interface link to a harness: one interface on each side is connected (e.g. partA's I2C ↔ partB's I2C).                                                                    | Write       | Board tab |
| `link_functions`         | Map a single function (wire/signal) on side A to its counterpart on side B inside an existing interface link.                                                                    | Write       | Board tab |
| `preview_function_links` | Read-only: candidate A↔B function pairings for a harness's interface link (matched by name + domain, existing links marked, per-row validity).                                   | Read        | Board tab |
| `batch_link_functions`   | Create multiple function links (wires) on a harness in one atomic, undoable call: preferred over repeated link\_functions.                                                       | Write       | Board tab |
| `auto_link_interfaces`   | Pick the most compatible interface pair between the harness's two parts that is NOT already linked by a sibling harness, and create the interface link.                          | Write       | Board tab |
| `auto_link_functions`    | Auto-link function pairs on a harness by matching names/domains and auto-allocating resources when available.                                                                    | Write       | Board tab |
| `get_harness_details`    | Inspect a harness: computed display name (same label the user sees), DRC connection state, the interface link (per-side instance + definition ids and names) and function links. | Read        | Board tab |
| `remove_harness_link`    | Remove a link from within a harness.                                                                                                                                             | Destructive | Board tab |
| `rename_harness`         | Rename a harness. The new name shows on the canvas and in the Inspector.                                                                                                         | Write       | Board tab |

## Resources

| Tool                                             | What it does                                                                                                                                                                                                       | Access      | Runs in   |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | --------- |
| `list_part_resources`                            | List a part's resources: the physical endpoints (pins, ports, mounting holes, fittings) that interface functions can be allocated to.                                                                              | Read        | Board tab |
| `list_eligible_resources_for_interface_function` | List the resources that can validly fulfill a given interface function on a part (e.g. which GPIO pins can carry the i2c\_sda function for I2C-0).                                                                 | Read        | Board tab |
| `allocate_resource_to_interface_function`        | Bind an interface function to a specific physical resource: e.g. assign I2C-0's sda function to GPIO pin 4 on a Pi. 'Allocation' is how Protoboard pins down which physical pin/port carries which logical signal. | Write       | Board tab |
| `deallocate_resource`                            | Remove an allocation (disconnect a resource from an interface function).                                                                                                                                           | Destructive | Board tab |
| `auto_allocate_resource`                         | Pick the best-fitting eligible resource for an interface function and allocate it.                                                                                                                                 | Write       | Board tab |
| `auto_allocate_harness_resources`                | Auto-allocate resources for all unallocated interface functions on both sides of a harness.                                                                                                                        | Write       | Board tab |

## Validation and review

| Tool                     | What it does                                                                | Access | Runs in   |
| ------------------------ | --------------------------------------------------------------------------- | ------ | --------- |
| `check_compatibility`    | Check if two interfaces are compatible for connection                       | Read   | Board tab |
| `run_drc`                | Run Design Rule Check (DRC) on the current board to find connection issues. | Read   | Board tab |
| `get_capacity_status`    | Get capacity and utilization status for a part                              | Read   | Board tab |
| `list_review_comments`   | List all review comments on the board with their IDs, status, and content   | Read   | Board tab |
| `add_review_comment`     | Add a review comment to the Board Review panel                              | Write  | Board tab |
| `update_review_comment`  | Edit the title or content of an existing review comment                     | Write  | Board tab |
| `resolve_review_comment` | Mark a review comment as resolved                                           | Write  | Board tab |

## Layout

| Tool                   | What it does                                                                                                                        | Access | Runs in   |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------ | --------- |
| `get_board_snapshot`   | Get a structured spatial map of the board: parts with positions and dimensions, harnesses with handle positions, and canvas bounds. | Read   | Board tab |
| `get_layout_issues`    | Detect layout problems: overlapping parts, handles facing the wrong direction, etc.                                                 | Read   | Board tab |
| `find_empty_space`     | Find an empty position on the canvas to place a new part without overlapping existing parts.                                        | Read   | Board tab |
| `move_harness_handle`  | Move a harness handle to a specific side of a part.                                                                                 | Write  | Board tab |
| `auto_route_harnesses` | Automatically position harness handles to face connected parts and distribute evenly.                                               | Write  | Board tab |
| `auto_arrange_parts`   | Clean up part positions on the board.                                                                                               | Write  | Board tab |

## Groups and notes

| Tool                 | What it does                                                                                  | Access      | Runs in   |
| -------------------- | --------------------------------------------------------------------------------------------- | ----------- | --------- |
| `create_group`       | Create a new group node on the canvas.                                                        | Write       | Board tab |
| `update_group_style` | Update a group's title and/or color.                                                          | Write       | Board tab |
| `move_group`         | Move a group to a new top-left position.                                                      | Write       | Board tab |
| `resize_group`       | Resize a group.                                                                               | Write       | Board tab |
| `add_to_group`       | Add an existing part or annotation to a group.                                                | Write       | Board tab |
| `remove_from_group`  | Remove a node from whichever group it currently belongs to (no-op if it's already top-level). | Destructive | Board tab |
| `create_annotation`  | Create a sticky-note annotation on the canvas.                                                | Write       | Board tab |
| `update_annotation`  | Replace an annotation's body text.                                                            | Write       | Board tab |

## Board

| Tool                         | What it does                                                                                              | Access      | Runs in   |
| ---------------------------- | --------------------------------------------------------------------------------------------------------- | ----------- | --------- |
| `get_board_summary`          | Get a summary of the current board state including parts, harnesses, and connections                      | Read        | Board tab |
| `list_elements`              | List entities of a given type on the current board.                                                       | Read        | Board tab |
| `delete_element`             | Delete an element from the board by its ID.                                                               | Destructive | Board tab |
| `get_board_identity_summary` | Read the board's Board Identity: name, description, requirements and their status, tasks, tags and notes. | Read        | Board tab |
| `update_board_identity`      | Edit the board's Board Identity (name, description, requirements, tasks, tags and notes) in one call.     | Write       | Board tab |
| `export_board`               | Export the connected board as a complete .protoboard document that can be imported again.                 | Read        | Board tab |
| `import_board`               | Import a serialized .protoboard document into the connected board, replacing its current contents.        | Destructive | Board tab |

## Bill of materials

| Tool                               | What it does                                                                                       | Access      | Runs in   |
| ---------------------------------- | -------------------------------------------------------------------------------------------------- | ----------- | --------- |
| `get_bom_items`                    | List slim normalized BOM items for the current board.                                              | Read        | Board tab |
| `get_bom_item_details`             | Get detailed normalized BOM and supplier information for a single BOM item by template ID.         | Read        | Board tab |
| `get_bom_export_options`           | Describe the BOM export options available in the Protoboard UI.                                    | Read        | Board tab |
| `get_project_cost_estimate`        | Compute the board's BOM pricing and estimated total cost from its supplier records.                | Read        | Board tab |
| `refresh_bom_prices`               | Refresh prices for the board's existing BOM supplier records (the Fetch Prices action in the app). | Write       | Board tab |
| `set_active_bom_supplier`          | Set the active supplier record for a BOM item.                                                     | Write       | Board tab |
| `mark_bom_supplier_price_reviewed` | Mark an existing BOM supplier price as freshly reviewed without changing the price.                | Write       | Board tab |
| `upsert_bom_supplier_record`       | Create or update a board-local supplier record for a BOM item.                                     | Write       | Board tab |
| `remove_bom_supplier_record`       | Remove a board-local supplier record from a BOM item.                                              | Destructive | Board tab |

## Research

| Tool              | What it does                                                             | Access | Runs in   |
| ----------------- | ------------------------------------------------------------------------ | ------ | --------- |
| `search_web`      | Search the web for current information.                                  | Read   | Server    |
| `fetch_url`       | Fetch and extract a specific URL with safety checks.                     | Read   | Server    |
| `search_docs`     | Search Protoboard documentation specifically.                            | Read   | Server    |
| `fetch_datasheet` | Fetch and summarize a datasheet from a URL (domain must be in allowlist) | Read   | Board tab |

## Requests and feedback

| Tool                  | What it does                                                                                                     | Access          | Runs in   |
| --------------------- | ---------------------------------------------------------------------------------------------------------------- | --------------- | --------- |
| `submit_part_request` | Ask the ProtoPart library team to add a new part. Creates a public request on the ProtoPart GitHub repository.   | Files a request | Board tab |
| `submit_part_fix`     | Report a problem with an existing library part, such as wrong specs, a missing datasheet or unavailable pricing. | Files a request | Board tab |
| `submit_app_feedback` | Send a bug report or feature request about the Protoboard app to the Protoboard team.                            | Files a request | Board tab |

## Resources

The server also publishes read-only reference documents as MCP resources. Your agent can read them with its resource tool before it edits parts or wiring.

| Resource                            | Contents                                                                           |
| ----------------------------------- | ---------------------------------------------------------------------------------- |
| `protoboard://examples/{name}`      | Worked ProtoPart examples (for example arduino-nano, i2c-sensor, motor-controller) |
| `protoboard://kits`                 | Kits you can restrict a board to                                                   |
| `protoboard://kits/{kitId}`         | One kit's parts and quantities                                                     |
| `protoboard://protocols/canonical`  | Canonical protocol names and compatible role pairs                                 |
| `protoboard://reference/part-icons` | Canvas icons a part template can use                                               |
| `protoboard://schema/protopart`     | The ProtoPart JSON schema                                                          |
| `protoboard://skills/{name}`        | Design policy sheets (the same guidance ProtoBot follows)                          |
| `protoboard://taxonomy`             | The library category tree                                                          |

## Prompts

Prompts appear as slash commands in clients that support them.

| Prompt        | Purpose                |
| ------------- | ---------------------- |
| `create_part` | Create a new ProtoPart |

## Not available over MCP

Plan proposals, long-run checkpoints and ProtoBot's own skill loading belong to the ProtoBot chat in the app. External agents use their own planning tools instead.

## Related pages

* [Agent Bridge setup](https://docs.protoboard.xyz/agent-bridge/setup.md): connect a client before you call any tool
* [Agent Bridge troubleshooting](https://docs.protoboard.xyz/agent-bridge/troubleshooting.md): queued calls, closed tabs and auth errors
* [What ProtoBot can change](https://docs.protoboard.xyz/protobot/what-protobot-can-change.md): the same tools from inside the app
* [Request or fix a part](https://docs.protoboard.xyz/parts/request-or-fix-a-part.md): what happens after `submit_part_request`
