find_item

Resolves a canvas item id to the project that contains it. Use it when an agent is handed an item id — e.g. one copied from the client by the user — but has no project id, since every editing tool (update_item_property, style_item, delete_item, connect_items) requires one.

Without it the only way to resolve an id is to call get_project for every candidate project and scan the returned item list.

Tool name: find_item

Parameters

Parameter	Type	Required	Default	Description
itemId	string	Yes	—	The canvas item id to resolve.
projectId	string	No	—	Restrict the lookup to this project instead of searching all accessible projects.
maxProjects	number	No	50	Max projects to search when no projectId is given.
searchTemplates	boolean	No	false	Also search template projects.

Returns

The owning project plus the item, in the same shape as the items of get_project:

{
  "projectId": "a1b2c3d4-...",
  "projectName": "Product Roadmap",
  "tenantId": 42,
  "projectsSearched": 3,
  "item": {
    "id": "a1e511f7-...",
    "kind": "LabelChart",
    "chartType": 1,
    "position": { "x": 100, "y": 200 },
    "size": { "width": 240, "height": 48 },
    "text": "Q3 Goals"
  }
}

projectsSearched is how many projects were loaded before the hit — 1 when projectId was given.

When the item is not found, the tool returns an error whose message starts with NOT_FOUND:.

Search Order and Scope

• Without projectId, the caller's projects are searched most recently updated first, up to maxProjects. The item a user just copied is almost always in a recently touched project, so the hit usually comes within the first few.
• Projects that cannot be loaded are skipped rather than failing the lookup.
• Templates are excluded unless searchTemplates is set; they are then merged into the same most-recently-updated ordering.
• Like every tool, the search only covers the environment this MCP server targets. An id from a different environment reports NOT_FOUND.

tip

Pass projectId whenever it is already known. It turns the scan into a single project load and confirms the id without transferring the full item list of a large map.

Example

"Write 'Shipped' into label a1e511f7-…"

{ "itemId": "a1e511f7-..." }

Then feed the returned projectId into update_item_property.