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

Text Search Columns

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