productplan-mcp-server

Overview Schema Source Related Servers Discussions Admin

get_roadmap_bars

Read-only

Retrieve roadmap bars (features/items) with filters for lane, tag, legend, date range, or name. Returns dates, lane, legend, tags, and progress for each matching item.

Instructions

Get bars (features/items) on a roadmap, optionally filtered.

USE WHEN: "What's on the roadmap?", "Show planned features", "What's starting in Q2?", "Bars in the Mobile lane tagged urgent" Server-side filters (sent to ProductPlan): name_contains, starts_after/starts_before, ends_after/ends_before (YYYY-MM-DD, inclusive), is_container, sort ("starts_on asc"). Client-side filters (applied here to every fetched bar, before the 50-item cap): lane (name or ID), legend (name), tag. Exact, case-insensitive. Returns bars with ID, name, starts_on/ends_on, lane_name and lane_id, legend, tags, percent_done, is_container, and parked. For a bar's description and custom fields, use get_bar. FAILS WHEN: roadmap_id not found (use list_roadmaps); a date is not YYYY-MM-DD; sort names a field outside the allowed list (the error lists them). Says "No bars matched the filters" when filters exclude everything.

Input Schema

TableJSON Schema

Name	Required	Description
`tag`	No	Only bars carrying this tag (client-side, case-insensitive)
`lane`	No	Only bars in this lane, by name or lane ID (client-side, case-insensitive)
`sort`	No	Sort as "field" or "field asc\|desc" (server-side). Fields: id, name, starts_on, ends_on, is_container, created_at, updated_at
`legend`	No	Only bars with this legend name (client-side, case-insensitive; names from get_roadmap_legends)
`ends_after`	No	Only bars ending on or after this date, YYYY-MM-DD (server-side)
`roadmap_id`	Yes	Roadmap ID
`ends_before`	No	Only bars ending on or before this date, YYYY-MM-DD (server-side)
`is_container`	No	true for container bars only, false to exclude containers (server-side)
`starts_after`	No	Only bars starting on or after this date, YYYY-MM-DD (server-side)
`name_contains`	No	Only bars whose name contains this text (case-insensitive, server-side)
`starts_before`	No	Only bars starting on or before this date, YYYY-MM-DD (server-side)

Output Schema

TableJSON Schema

Name	Required	Description	Default
`data`	Yes	The ProductPlan payload (object or array) returned by the API, passed through verbatim
`summary`	Yes	Human-readable summary of the result (e.g. "Found 3 roadmaps")

Schema Changelog

Changes observed during successful MCP inspections.

Changed11 schema fields changedv6.0.0Sep 25, 2026

addedInput schema / properties / ends_after

Added value: +{
+  "description": "Only bars ending on or after this date, YYYY-MM-DD (server-side)",
+  "examples": [
+    "2026-01-01"
+  ],
+  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+  "type": "string"
+}

addedInput schema / properties / ends_before

Added value: +{
+  "description": "Only bars ending on or before this date, YYYY-MM-DD (server-side)",
+  "examples": [
+    "2026-01-01"
+  ],
+  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+  "type": "string"
+}

addedInput schema / properties / is_container

Added value: +{
+  "description": "true for container bars only, false to exclude containers (server-side)",
+  "type": "boolean"
+}

addedInput schema / properties / lane

Added value: +{
+  "description": "Only bars in this lane, by name or lane ID (client-side, case-insensitive)",
+  "type": "string"
+}

addedInput schema / properties / legend

Added value: +{
+  "description": "Only bars with this legend name (client-side, case-insensitive; names from get_roadmap_legends)",
+  "type": "string"
+}

addedInput schema / properties / name_contains

Added value: +{
+  "description": "Only bars whose name contains this text (case-insensitive, server-side)",
+  "type": "string"
+}

addedInput schema / properties / sort

Added value: +{
+  "description": "Sort as \"field\" or \"field asc|desc\" (server-side). Fields: id, name, starts_on, ends_on, is_container, created_at, updated_at",
+  "examples": [
+    "name asc"
+  ],
+  "pattern": "^(id|name|starts_on|ends_on|is_container|created_at|updated_at)( (asc|desc))?$",
+  "type": "string"
+}

addedInput schema / properties / starts_after

Added value: +{
+  "description": "Only bars starting on or after this date, YYYY-MM-DD (server-side)",
+  "examples": [
+    "2026-01-01"
+  ],
+  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+  "type": "string"
+}

addedInput schema / properties / starts_before

Added value: +{
+  "description": "Only bars starting on or before this date, YYYY-MM-DD (server-side)",
+  "examples": [
+    "2026-01-01"
+  ],
+  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+  "type": "string"
+}

addedInput schema / properties / tag

Added value: +{
+  "description": "Only bars carrying this tag (client-side, case-insensitive)",
+  "type": "string"
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "data": {
+      "description": "The ProductPlan payload (object or array) returned by the API, passed through verbatim",
+      "type": "object"
+    },
+    "summary": {
+      "description": "Human-readable summary of the result (e.g. \"Found 3 roadmaps\")",
+      "type": "string"
+    }
+  },
+  "required": [
+    "summary",
+    "data"
+  ],
+  "type": "object"
+}

First observedv5.0.0Mar 9, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint annotation, the description discloses behavior an agent could not infer: the 50-item cap, that client-side filters apply 'to every fetched bar, before the 50-item cap,' that date filters are inclusive, that client-side filters are exact and case-insensitive, and the exact no-results message. These are genuine behavioral disclosures that materially affect how the agent should invoke the tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long, but every section earns its place: purpose first, then USE WHEN triggers, then filter semantics grouped by execution site, then return fields, then FAILS WHEN. The labeled sections (USE WHEN / FAILS WHEN) make it scannable, and for an 11-parameter tool with complex filter behavior, the density is justified rather than padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the 11-parameter complexity, this description is complete: it covers failure modes, alternative routing for both more detail (get_bar) and roadmap discovery (list_roadmaps), filter semantics, ordering with the 50-item cap, and return fields — even though an output schema exists so return-value explanation wasn't required. Nothing an agent needs to invoke correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value: it groups the 11 parameters into server-side vs client-side filters and explains the practical consequence of that split (where they are applied, ordering with the 50-item cap, exactness). This explains the sort pattern's meaning, the allowed field list, and date inclusivity, which goes beyond what the schema's per-parameter descriptions state.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'Get bars (features/items) on a roadmap, optionally filtered.' It distinguishes itself from siblings by explicitly routing detail lookups to get_bar ('For a bar's description and custom fields, use get_bar'), and the sibling list shows get_roadmap_bars sits apart from get_bar, get_bar_children, and get_roadmap_complete. An agent can tell exactly what this tool does and what it does not do.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'USE WHEN' section gives concrete user-intent examples ('What's on the roadmap?', 'What's starting in Q2?', 'Bars in the Mobile lane tagged urgent'). The 'FAILS WHEN' section names failure triggers and routes to alternatives ('roadmap_id not found (use list_roadmaps)'). This is explicit when-to-use guidance with exclusion and alternative routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server