MCP server: get_pql_reference is uncallable — schema omits `action` but the dispatcher requires it

[faraon87]

Summary

The get_pql_reference tool on the hosted MCP server (https://mcp.plane.so/http/mcp) cannot be called in any form. The published tool schema and the server-side dispatcher disagree about a required action parameter, so every call fails.

Reproduction

Three call forms, three failures:

Call	Result
get_pql_reference() (no arguments)	Error: get_pql_reference requires an action. It takes: read.
get_pql_reference(detail="brief")	Same error, verbatim.
get_pql_reference(detail="brief", action="read")	1 validation error for call[get_pql_reference] / action / Unexpected keyword argument [type=unexpected_keyword_argument, input_value='read', input_type=str]

Why there is no valid call

The published JSON schema declares exactly one property, detail (enum: brief, full), and no action. The tool's own description states:

Actions: read (no required params; optional detail) -- this tool has no action parameter.

The dispatcher demands the parameter the schema forbids, and the validator rejects it when supplied.

Every other tool on this server takes action as a required enum. The likely cause is a generic dispatcher that requires action on all tools, while the schema generator correctly omitted it for this one.

Expected

get_pql_reference returns the PQL syntax reference, honouring the optional detail parameter.

Impact

This is the documented entry point for PQL syntax. A caller who hits the contradictory error concludes PQL is unusable and falls back to paging every work item client-side. I did exactly that before finding the workaround below: a question that one PQL filter answers in a single call instead paged through 1,069 work items.

Workaround

The reference is reachable. Send a deliberately invalid PQL to any tool accepting a pql parameter, and the error payload carries the whole document:

workitem count project_id="<uuid>" pql='__nonexistent_field__ = "x"'

Returns {error, failed_pql, pql_reference, hint}, where pql_reference is the complete reference — fields, operators, date/user/cycle functions, predicate and relation functions, custom-property syntax, the 5-condition limit, and examples. It appears to be the same content the broken tool should serve, so this looks like a dispatcher/schema wiring problem rather than missing content.

Environment

• Hosted MCP server at https://mcp.plane.so/http/mcp, transport http
• Client: Claude Code
• Observed 2026-09-14

[breken-ai]

Confirmed the contract is unsatisfiable as published: omitting action reaches a dispatcher that requires it, while supplying action=read is rejected by the tool validator because action is absent from the schema. That leaves no request shape accepted by both layers. The narrow fix is to make the dispatcher honor this tool's actionless contract, or add action: read to the schema and handler consistently. The hosted MCP implementation does not appear in this public repository, so there is no code surface here for a community PR, but the failure is isolated to the tool wiring rather than the PQL reference content.

Built by breken, your AI support engineer - breken.ai finds the bug, proves the fix with unmatched RCA, answers customers in your voice, and keeps your code and support docs clean - this one's on us.