productplan-mcp-server

by olgasafonova

Overview Schema Source Related Servers Discussions Admin

Local

get_roadmap_legends

Read-only

Retrieve the legend names (bar colors) available on a roadmap to identify which legend to use when coloring bars.

Instructions

Get the legend names (bar colors) for a roadmap.

USE WHEN: "What colors are available?", "Show the legend", "Which legend can I color bars with?" Returns an array of legend names. The ProductPlan API exposes legends by name only: there is no legend ID or hex color to return. Pass a name as legend on manage_bar, bulk_update_bars, or bulk_create_bars to color a bar. For custom field definitions (labels, dropdown allowed_values), use get_roadmap instead. To find bars by legend, use get_roadmap_bars with legend. FAILS WHEN: roadmap_id not found (use list_roadmaps).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`roadmap_id`	Yes	Roadmap ID

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.

Changed1 schema field changedv6.0.0Sep 25, 2026

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.4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, and the description builds on that by revealing the API limitation: legends are name-only, with no ID or hex color. It also explains how the returned names are consumed by manage_bar and bulk tools. No contradiction with annotations; adds behavioral nuance beyond the read-only flag.

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

Conciseness4/5

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

The description is structured with clear sections (USE WHEN, returns, usage, alternatives, FAILS WHEN), and every sentence contributes value. It is slightly longer than the absolute minimum, but the length is justified by the routing and usage details, and it remains front-loaded with the core purpose.

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?

For a single-parameter read-only tool with a well-documented schema and output schema, the description covers everything an agent needs: purpose, usage cues, alternative tools, failure handling, and how to apply the results. Nothing essential is missing.

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

Parameters3/5

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

There is only one parameter, roadmap_id, and the schema description 'Roadmap ID' fully covers its meaning. The tool description adds no extra semantics for this parameter, but with 100% schema coverage, the baseline of 3 is appropriate and no further clarification is needed.

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 clearly states the tool returns legend names (bar colors) for a roadmap, specifying the exact resource and action. It also explicitly distinguishes itself from get_roadmap (custom field definitions) and get_roadmap_bars (finding bars by legend), making it unambiguous among siblings.

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 description includes a dedicated 'USE WHEN' section with concrete example queries, and a 'FAILS WHEN' section with fallback guidance (use list_roadmaps). It also names two alternative tools and the conditions for choosing them, giving agents explicit routing instructions.

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

Deploy Server