P4 Plan Find Query Syntax

The search_tasks tool accepts a findQuery parameter for searching using P4 Plan's query language. Use it to filter by status, assignee, priority, dates, or any combination. For simple name search use Itemname:Text("text").

⚠️ Column names must be spelled exactly as shown below. There is no `priority` column — use `Productbacklogpriority`, `Sprintpriority`, or `Bugpriority`. There is no `itemType` — use `Itemtype`. No spaces in column names, exact casing. Values use human-readable strings like "Very high priority", NOT enum values like "veryHigh".

Common Mistakes

Operators

Status Values

Example: Status="Not done" OR Status="In progress"

Priority Columns (there is NO generic "priority")

There are three separate priority columns — each applies to a different item type. All use the same values:

Priority values (same for all three columns):

Item Types

Use Itemtype to filter by type. Exact values:

Example: Itemtype="Bug" AND Status="Not done"

Severity (Bugs only — use letter codes)

Example: Severity="A" OR Severity="B"

Confidence and Risk

Example: Confidence="High", Risk="Low"

Other Columns

The Two ID Columns

P4 Plan items have two different IDs, and both are queryable. Picking the wrong one is the most common cause of a search that returns nothing.

Both are returned on every item -- as id (database) and localID (local) -- so you rarely need to look either up. When a user quotes a bare number, decide by where it came from, not by how long it is:

• Read off the P4 Plan UI's "ID" column, or spoken as "bug 4217" / "item 42" -> local ID,

use ID=.

• Copied from a tool response, a P4 Plan URL, or handed over by another agent -> database ID,

pass it straight to get_tasks.

If the origin is genuinely unclear, ask, or try Databaseid= and fall back to ID= -- do not guess from digit count, since the two ranges overlap.

# User says "look at bug 4217" -- resolve the UI number to a real item
ID=4217

# Confirm which item a database ID refers to, scoped to one section
Databaseid=500100

Never binary-search for a local ID. A single ID= query resolves it directly.

An item's localID is a property of the item, not of the query -- it is resolved from the item alone and is the same whichever section you search. projectID is not: for an item listed in two sections (a committed backlog item, say) a search reports the section you searched, while get_tasks reports the section the item was created in. Use id for identity.

Local IDs are unique only within one section. The Backlog, Planning and QA sections of the same project can each have an item with ID=42, so always run an ID= query against the section the user means, and say which section you searched when you report the result.

Workflow and Pipeline Columns

Use the workflow/pipeline name exactly as get_workflows returns it. This matches both status workflows and pipelines — a pipeline match returns the items carrying the pipeline, not the pipeline tasks it spawned. See the pipeline skill for how to list the steps themselves.

Text Search Columns

Quotes Inside Text() Searches

Item names in P4 Plan routinely contain double quotes. Escape them as \" inside the literal -- substituting a name verbatim breaks the parse:

# Item actually named:  Checkout redesign ("Buy now" flow)

# CORRECT -- embedded quotes escaped
Subprojectpath:Text("Checkout redesign (\"Buy now\" flow)")

# WRONG -- fails with the misleading error 'Space is not allowed here'
Subprojectpath:Text("Checkout redesign ("Buy now" flow)")

The error names whitespace, not quoting, so it is easy to misdiagnose. If a Text() search fails that way, check for unescaped quotes before touching anything else. Searching a distinctive quote-free fragment of the name also works and avoids the problem entirely.

Date/Time Columns

Comparison operators: =, <, >, <=, >=

Date range: fromdatetodate(2026-01-01, 2026-03-31) or fromdatetodate(now-7d, now)

Resource Columns

x

Boolean Conditions

Special Keywords

Custom Columns

Custom columns use their name directly: MyColumnName:Text("value"), MyColumnName=<number>, etc. The operator depends on the custom column type.

Example Queries

# All open bugs with critical severity
Itemtype="Bug" AND Status="Not done" AND Severity="A"

# High-priority bugs
Itemtype="Bug" AND Bugpriority="Very high priority"

# High-priority backlog items (NOT Bugpriority, NOT priority)
Productbacklogpriority="Very high priority" AND Status="Not done"

# Open bugs with high or critical severity
Itemtype="Bug" AND (Severity="A" OR Severity="B") AND NOT Status="Completed"

# Items assigned to a specific user
Assignedto:Resource("john.doe")

# Unassigned items in current sprint
GeneralconditionIncurrentsprint=true AND GeneralconditionNotassigned=true

# Items updated in the last 7 days
Lastupdatedon>=fromdatetodate(now-7d, now)

# All user stories with points
GeneralconditionUserstory=true AND Points>0

# Overdue scheduled tasks
ScheduledconditionOverdue=true

# Items with specific text in comments
Comments:Text("blocker")

# Blocked items
Status="Blocked"

# In-progress items with high sprint priority
Status="In progress" AND Sprintpriority="High priority"

# Bugs by severity
Itemtype="Bug" AND Severity="A"

Handling "Limit Exceeded" Errors

When search_tasks returns "limit exceeded", the result set is too large for one query. Do NOT retry the same query or ask the user. Instead, decompose the query by splitting it into multiple narrower sub-queries along a known dimension, run them one at a time, and aggregate the results.

Decomposition Dimensions (pick the one that fits the user's intent)

Strategy

1. Choose the dimension that best matches what the user is asking about. If the user asks "show me bugs by severity", split on Severity. If they ask "how many bugs are open", split on Status.
2. Construct sub-queries by adding AND <dimension>=<value> to the original query for each possible value.
3. Run sub-queries one at a time and collect the count from each result.
4. Aggregate — sum counts for totals, or present per-value counts for charts/breakdowns.
5. If a sub-query still exceeds the limit, decompose it further by adding a second dimension (e.g., Severity AND Status).

Examples

# User asks: "Show me a pie chart of all bugs by severity"
# Original query that would fail: Itemtype="Bug"
# Decompose by Severity:

Severity="A"  → count: 781
Severity="B"  → count: 2030
Severity="C"  → count: 3069
Severity="D"  → count: 1517
# Total: 7397. Render pie chart from these 4 counts.

# User asks: "How many open bugs per priority?"
# Decompose by Bugpriority, all with AND Status="Not done":

Status="Not done" AND Bugpriority="Very high priority"  → count: ...
Status="Not done" AND Bugpriority="High priority"       → count: ...
Status="Not done" AND Bugpriority="Medium priority"     → count: ...
Status="Not done" AND Bugpriority="Low priority"        → count: ...
Status="Not done" AND Bugpriority="Very low priority"   → count: ...

Key Rules

• Never ask the user what to do when you get "limit exceeded" — decompose automatically.
• Only use the `count` from each sub-query when building summaries/charts — you don't need the individual items.
• If you only need counts (for charts, summaries), this is very efficient: 4-6 lightweight queries instead of one huge one.

Related Skills

• Project Navigation -- finding projects and items
• Task Management -- working with tasks