Analyzes Linear project issues and blocking relations to identify keystone tickets and blockers using dominator analysis.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@PinchMCP What ticket unblocks the most downstream work in my project?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Find the keystone ticket — the one that, once done, unblocks the most downstream work.
An MCP server between Claude Code and Linear. It reads a project's issues and their blocking relations, fuses them into an in-memory dependency graph, and points you at the leverage — via dominator analysis, not a bare score. Then it goes further: the critical path (CPM), inferred code coupling, cold-start predictions for not-yet-built tickets, and graph hygiene.
Deterministic, read-only, no LLM in the server — it analyzes; you decide.
Status —
v0.4.0. Phases I–III shipped (9 tools spanning the explicit dependency graph, inferred code coupling, cold-start prediction, graph hygiene, and feature-decomposition grounding), plus the first Phase IV deliverable — 10 tools in total. Phase IV (Slack + Granola integrations) is on the roadmap — the Granola reconciliation server side has shipped asreconcile_notes; the ingestion/delivery integration remains. Seedocs/ROADMAP.mdfor done vs. planned anddocs/SECURITY.mdfor the trust model.
There is nothing to deploy. PinchMCP is a stdio MCP server: Claude Code launches it as a local subprocess on demand and talks to it over stdin/stdout. "Running it" just means the built code lives on the machine where you run Claude Code — no port, no daemon, no hosting. Each developer who wants it does this once on their own machine, with their own Linear key.
End to end:
# 1. Get the code and build it (needs Node 22+)
git clone https://github.com/0xdefence/PinchMCP.git
cd PinchMCP
npm install
npm run build# 2. Get a Linear personal API key
# Linear → Settings → Security & access → Personal API keys → Create key
# (copy the lin_api_… value)
# 3. Find the project_id you want to analyze
curl -s https://api.linear.app/graphql \
-H "Authorization: lin_api_your_key" \
-H "Content-Type: application/json" \
-d '{"query":"{ projects(first: 50) { nodes { id name } } }"}'// 4. Register the server with Claude Code.
// Create .mcp.json in your project root (or ~/), using the ABSOLUTE path
// to dist/src/index.js printed by `pwd`:
{
"mcpServers": {
"pinch-mcp": {
"command": "node",
"args": ["/absolute/path/to/PinchMCP/dist/src/index.js"],
"env": { "LINEAR_API_KEY": "lin_api_your_key" }
}
}
}5. Restart Claude Code, run /mcp to confirm "pinch-mcp" is connected,
then ask: "Rank the keystones for Linear project <project_id>."Each step is expanded in the sections below (Install · API key · project_id · Connect to Claude Code · Use it).
Related MCP server: SYKE
Questions teams actually ask, with distinct answers:
Keystone — "What single ticket, once done, unblocks the most downstream work?" Answered by dominator analysis: a ticket is high-leverage when every path to many downstream tickets must pass through it. This is not the same as "the ticket that touches the most things" — a bottleneck that gatekeeps 5 tickets beats a ticket that merely precedes 20 reachable ones.
Critical path — "What sets the total timeline?" Answered by CPM over estimates: the longest-duration dependency chain, plus how much slack every other ticket has. Distinct from keystone — max-leverage unlock vs. what sets duration.
Blockers — "For this one ticket, what must finish first, and what does it unblock?" Answered by a transitive walk up and down the dependency chain.
Explainability is the product. Output says why: "every path to ENG-2, ENG-3 passes through ENG-1," not a bare score.
Tool | Input | What it returns |
| (none) | Lists the workspace's projects with their ids and URL slugs, so you can pick a |
|
| Fetches issues + relations and (re)builds the cached graph. Reports issue/edge counts. |
|
| Tickets ranked by leverage (dominated-subtree size), with plain-language explanations, plus warnings (cycles) and ungrounded tickets. |
|
| CPM over estimates: the longest-duration chain that sets the timeline, plus per-ticket slack. Answers "what sets total duration" (vs keystones' "max leverage unlock"). Unestimated tickets default to 1. |
|
| Transitive blockers (must finish first) and downstream unblocks for one ticket. |
|
| Infers coupling from code (shared files, intra-repo imports, git co-change) and suggests ticket links Linear doesn't record — evidence-backed, confirm-before-acting. Never folded into keystone/critical_path. |
|
| Cold-start: predicts which code areas a ticket will likely touch and which tickets likely couple, from ticket text vs a keyword index of the repo — for backlog tickets with no code yet. Planning aid; never used in keystone/critical_path. |
|
| Reports graph hygiene gaps — cycles, isolated tickets, stale blockers (blocker already done), and keystones missing an estimate or owner. Deterministic; asserts/writes nothing. |
|
| Cold-start grounding for a free-text feature: predicted code areas + related existing tickets, for the client to decompose. Never creates tickets. |
|
| Reconciles client-extracted meeting-note items (blockers, ticket refs, feature/bug mentions) against the graph: unrecorded blockers, ref status vs what was said, overlap with existing tickets. Extraction is the client's job; pinch stays deterministic and never writes. |
Across the analysis tools, project_id accepts a Linear project name,
URL slug, or UUID — it's resolved internally, so you can speak in names
("rank keystones for 0xDefence") and PinchMCP maps it to the right project.
Node.js 22 or newer (active LTS; Node 18 is end-of-life). The server uses
the global fetch.
A Linear account and a personal API key.
Claude Code (or any MCP client that can launch a stdio server).
git clone https://github.com/0xdefence/PinchMCP.git
cd PinchMCP
npm install
npm run buildnpm run build compiles TypeScript to dist/. The server entrypoint is
dist/src/index.js.
Verify it built and starts (it should wait for stdio input, then exit cleanly on EOF):
LINEAR_API_KEY=dummy node dist/src/index.js < /dev/null && echo "starts OK"With no key it should fail fast with a clear message:
node dist/src/index.js < /dev/null # -> Error: LINEAR_API_KEY environment variable is required.Linear → Settings → Security & access → Personal API keys.
Create key, give it a name, copy the value (looks like lin_api_…).
The key is passed to the server as the LINEAR_API_KEY environment variable.
For local CLI use you can also copy .env.example to .env and set it there.
Never commit your key.
.envis gitignored. The key grants access to your Linear workspace.
Fetched project graphs are cached in memory for 5 minutes by default. Set
PINCH_CACHE_TTL_MS (a positive integer, in milliseconds) to override the TTL.
build_feature_graph always forces a refresh regardless of the cache.
project_idThe analysis tools take a Linear project UUID or the URL slug — not a
display name (Linear's project(id:) lookup rejects names). Three ways to get a
valid value:
Ask Claude Code once the server is connected: "list my Linear projects"
runs the list_projects tool and prints every project with its id and slug.
From the project URL — linear.app/<workspace>/project/<name>-<slugId>.
Paste the whole <name>-<slugId> slug or just the trailing hex; both work.
Via curl:
curl -s https://api.linear.app/graphql \
-H "Authorization: $LINEAR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"{ projects(first: 50) { nodes { id name slugId } } }"}' | jqAny id or slugId from the output works as project_id.
PinchMCP is a stdio MCP server. Point Claude Code at the built entrypoint with your API key in the environment.
Create .mcp.json in the root of the repo where you want to use it (or your home
directory for global use):
{
"mcpServers": {
"pinch-mcp": {
"command": "node",
"args": ["/absolute/path/to/PinchMCP/dist/src/index.js"],
"env": { "LINEAR_API_KEY": "lin_api_your_key_here" }
}
}
}Use the absolute path to dist/src/index.js. Restart Claude Code (or
reconnect MCP servers) so it picks up the config.
claude mcp add pinch-mcp \
-e LINEAR_API_KEY=lin_api_your_key_here \
-- node /absolute/path/to/PinchMCP/dist/src/index.jsIn Claude Code, run /mcp — you should see pinch-mcp connected with ten
tools. If it shows as failed, check: the path is absolute and points at
dist/src/index.js, you ran npm run build, and LINEAR_API_KEY is set.
Once connected, just ask Claude Code in natural language — it will call the tools. Examples:
"Build the feature graph for project <project_id> and rank the keystones."
"Which ticket is the biggest bottleneck in <project_id>?"
"What's blocking ENG-42, and what does it unblock?"
Claude Code decides when to call build_feature_graph, rank_keystones, and
explain_blockers, and explains the results using the tool output.
Claude Code ──tool call──▶ PinchMCP (stdio)
│
config ─▶ LinearGraphQLSource ──GraphQL──▶ api.linear.app
│
GraphCache (per project_id)
│
buildFeatureGraph
(normalize blocks/blocked_by → canonical edges)
│
┌───────────────┴───────────────┐
rankKeystones explainBlockers
(dominator tree, leverage) (transitive chain walk)
│ │
explainable text ◀── tool handlers ──▶ explainable textLinear layer (src/linear/) — a GraphQL client behind an IssueSource
interface (the seam where a future MCP-to-MCP client could slot in), plus
normalization of raw payloads into domain Issue/Relation types.
Graph layer (src/graph/) — pure, I/O-free functions:
buildFeatureGraph normalizes blocks/blocked_by into one canonical
"A unblocks B" edge direction, de-dups, drops out-of-project and self
edges, and keeps related/duplicate as side metadata.
rankKeystones adds a virtual entry node to all unblocked tickets, computes
a dominator tree (Cooper-Harvey-Kennedy), and sets each ticket's
leverage to the size of its dominated subtree.
explainBlockers walks predecessors/successors transitively.
Cache (src/cache.ts) — one built graph per project_id;
build_feature_graph forces a refresh.
Tools (src/tools/) — thin formatters turning graph results into
human-readable, explainable output.
A node's reachable descendants counts everything downstream, including work reachable by other paths too. A dominator is stricter: ticket X dominates ticket Y only if every path to Y passes through X. That's the real "if this slips, everything behind it slips" signal. The test suite includes a bottleneck graph proving these two metrics diverge.
docs/ARCHITECTURE.md — layers, modules, data types,
request flow, error handling, design decisions, and extension points.
docs/KEYSTONE-ALGORITHM.md — the dominator
analysis in depth: why dominators beat reachability, the Cooper–Harvey–Kennedy
computation, leverage, edge cases, and complexity.
docs/ROADMAP.md — what's shipped vs. planned across
Phase I (explicit graph), Phase II (code grounding), and Phase III
(generative scoping).
docs/DECOMPOSITION-WORKFLOW.md — how to
break a free-text feature into grounded Linear tickets using decompose_grounding,
Claude Code, and the Linear MCP together.
docs/RECONCILIATION-WORKFLOW.md — how to
reconcile client-extracted meeting-note items against the graph using
reconcile_notes, Claude Code, and the Linear MCP together.
docs/SECURITY.md — trust model: read-only, one local
secret (never logged), writes delegated to the Linear MCP, and how integrations
keep secrets with their own MCP.
npm test # full vitest suite
npm run dev # run from source via tsx (no build step)
npm run build # compile to dist/ (emits src only, via tsconfig.build.json)The graph algorithms are pure functions tested against synthetic fixtures with hand-computed dominator trees; the Linear adapter is tested against a recorded JSON fixture — no live API calls in the test suite.
Phase I (this explicit-graph slice) is shipped. Phase II adds the inferred
code-coupling graph + critical_path; Phase III adds generative scoping (break
features into tickets, surface gaps). Full status — done vs. not — is tracked in
docs/ROADMAP.md.
Issues are paged at 50 per request to stay under Linear's 10k query-complexity cap (up to 10,000 issues across pages). A single issue's relations beyond the first 50 are fetched via follow-up paginated queries, so no overflow is missed.
explain_blockers doesn't annotate cycles, though rank_keystones does.
Inferred direction from code coupling is not here yet — this slice uses only Linear's explicit, human-asserted relations.
Fetch a Linear project's issues and blocking relations and (re)build the in-memory dependency graph. project_id accepts a project name, URL slug, or UUID.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Linear project name, URL slug, or UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions 'rebuild' implying overwrite, and 'in-memory' suggests ephemerality, but doesn't disclose side effects, cost, or whether it modifies persistent state. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each earning their place. The first explains the action, the second details the parameter. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description covers the essential action and parameter. However, it could mention that the built graph is used by sibling tools, which would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description repeats the same info (project name, URL slug, or UUID) without adding new meaning. Baseline of 3 is appropriate as no added value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches issues and blocking relations and (re)builds an in-memory dependency graph for a Linear project. This distinguishes it from siblings that analyze or rank existing graphs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like 'rank_keystones' or 'critical_path'. The agent must infer that this tool builds the graph for subsequent analysis, but no explicit direction is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compute the critical path via CPM over ticket estimates: the longest-duration chain that sets the timeline, plus slack per ticket. Answers 'what sets total duration' (vs rank_keystones' 'max leverage unlock'). project_id accepts a project name, URL slug, or UUID.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Linear project name, URL slug, or UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that the tool computes based on ticket estimates and returns duration chain and slack, but does not mention side effects, auth requirements, or rate limits. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. First sentence explains functionality and outputs; second sentence provides usage context and parameter guidance. Perfectly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (one parameter, no output schema or nested objects), the description covers purpose, usage, and parameter type. It mentions output (slack, chain) but not format or example. Mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter. Description repeats that project_id accepts name, URL slug, or UUID, which matches the schema. No additional semantic enrichment beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it computes the critical path via CPM over ticket estimates, defines outputs (longest-duration chain, slack), and explicitly distinguishes it from sibling 'rank_keystones' by contrasting the questions each answers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use this tool vs sibling (answers 'what sets total duration' vs 'max leverage unlock'). Also clarifies that project_id accepts name, URL slug, or UUID, aiding correct input. No explicit when-not-to-use, but the contrast is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Given a free-text feature description, predict which code areas it will touch and which existing tickets overlap — grounding for the client to decompose it into tickets. Suggestions only; pinch never creates tickets (use the Linear MCP). project_id accepts a name/slug/UUID; repo_path is the local checkout; feature is the description to ground.
| Name | Required | Description | Default |
|---|---|---|---|
| feature | Yes | Free-text description of the feature to ground | |
| repo_path | Yes | Absolute path to the project's local git checkout | |
| project_id | Yes | Linear project name, URL slug, or UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It states the tool is non-destructive ('suggestions only') and does not create tickets, but fails to mention side effects, error handling, performance considerations, or response structure. For a prediction tool, this transparency is inadequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no redundant content. The first sentence concisely captures the core functionality. The second sentence provides parameter clarification and disclaimers. Slightly verbose but efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and annotations, the description should provide a clearer picture of the output format. It hints at predictions for code areas and existing tickets, but does not specify the structure or how to interpret results. It is adequate for basic use but leaves gaps that could confuse an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description adds minimal extra value. It rephrases parameter purposes (e.g., 'repo_path is the local checkout') but does not provide new constraints or usage details beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: predicting code areas and overlapping tickets from a free-text feature description. It distinguishes itself from siblings by mentioning it does not create tickets, directing users to the Linear MCP for ticket creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when not to use it (ticket creation) and names an alternative (Linear MCP). It also specifies acceptable input formats for project_id. However, it does not explicitly state when to use this tool versus other sibling tools like rank_keystones or surface_gaps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show what transitively blocks a ticket and what it transitively unblocks. project_id accepts a project name, URL slug, or UUID.
| Name | Required | Description | Default |
|---|---|---|---|
| ticket_id | Yes | ||
| project_id | Yes | Linear project name, URL slug, or UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry transparency. It mentions transitive analysis but does not disclose side effects (read-only assumed), authentication needs, output format, or rate limits. Minimal behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundancy. First sentence delivers purpose, second adds parameter detail. Efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite low complexity, the tool lacks output schema and the description fails to explain return structure. Requires inference about what 'show' means. Incomplete for effective agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only project_id described). Description repeats project_id's accepted formats but adds no new semantic insight for either parameter. ticket_id lacks description in both schema and text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool shows transitive blockers and unblockers for a ticket. The verb and resource are specific, and it distinguishes from siblings like 'critical_path' which likely focuses on path analysis rather than block relationships.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage when needing to understand blocker relationships, but no explicit guidance on when not to use or when to prefer alternatives like 'critical_path' or 'surface_gaps'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the workspace's Linear projects with their ids and slugs, so a project_id can be chosen. Linear's project lookup needs a UUID or URL slug, not a display name.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the output contains ids and slugs and explains why they are needed (Linear lookup requires UUID/slug). Lack of mention of pagination or ordering is a minor gap, but for a simple list tool it is mostly adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise, front-loaded sentences with no redundant information. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description fully equips an agent to use the tool correctly: it explains the output format, the use case, and why the tool is needed. No important gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters and schema coverage is 100%. The description adds value beyond the schema by detailing the return values (ids and slugs) and their purpose, which is sufficient for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists the workspace's Linear projects with their ids and slugs, specifying the exact purpose of enabling project_id selection for subsequent operations. It distinguishes itself from sibling tools which are unrelated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (when you need a project ID for Linear operations) but does not explicitly state when not to use or provide alternatives. However, sibling tools are sufficiently different that no exclusion is necessary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rank tickets by leverage: how much downstream work each one gatekeeps, via dominator analysis of the blocking graph. project_id accepts a project name, URL slug, or UUID.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Linear project name, URL slug, or UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral transparency. It explains the core action but omits details like read-only nature, required permissions, or behavior with edge cases (e.g., empty graph). This is insufficient for a tool performing complex analysis.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences covering purpose and parameter flexibility. Every word adds value, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema, the description fails to explain the rank format or how to interpret results. It provides the concept but not enough for a developer to fully understand the tool's output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds clarity by specifying that project_id accepts a project name, URL slug, or UUID. This goes beyond the schema description, adding semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies a unique action: ranking tickets by leverage via dominator analysis. It distinguishes this tool from siblings like critical_path and explain_blockers, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for identifying high-leverage tickets but does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives. It relies on the user to infer context from the technique mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Given structured items extracted from meeting notes (blockers, ticket refs, feature/bug mentions — extraction is the client's job), reconcile them against the Linear dependency graph: unrecorded blockers, ref status, overlap with existing tickets. Suggestions only — pinch never writes; use the Linear MCP to act. project_id accepts a name/slug/UUID; repo_path (optional) enables code-area grounding for mentions.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Client-extracted items from the notes | |
| repo_path | No | Optional absolute path to the project's local git checkout | |
| project_id | Yes | Linear project name, URL slug, or UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses a key behavioral trait: 'Suggestions only — pinch never writes', indicating read-only nature. It also implies the tool requires preprocessed input. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient: four sentences covering purpose, behavioral constraints, and parameter details with no redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description implies output are suggestions, but doesn't specify structure. It covers input, behavior, and parameter format adequately for a reconciliation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value by explaining repo_path's purpose ('enables code-area grounding') and framing items as 'blockers, ticket refs, feature/bug mentions', which clarifies the schema's discriminated union.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reconciles structured items from meeting notes against a Linear dependency graph, specifying the verb (reconcile) and resource (notes vs graph). It distinguishes from siblings like 'explain_blockers' by targeting extracted items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use ('extraction is the client's job') and when not ('pinch never writes; use the Linear MCP to act'). It also clarifies parameter format (project_id accepts name/slug/UUID). However, it doesn't explicitly compare to all siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Infer coupling between tickets from the code they touch (shared files, intra-repo imports, git co-change) and suggest links Linear doesn't record. Suggestions only — never asserted; never folded into keystone/critical_path. project_id accepts a name, slug, or UUID; repo_path is the absolute path to the project's local git checkout.
| Name | Required | Description | Default |
|---|---|---|---|
| repo_path | Yes | Absolute path to the project's local git checkout | |
| project_id | Yes | Linear project name, URL slug, or UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations present, so description carries full burden. It discloses the tool's non-authoritative nature ('never asserted') and dependencies (shared files, imports, co-change). No side effects or auth needs are mentioned, but appropriate for a suggestion tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences only; first sentence conveys purpose and scope with examples, second clarifies nature and parameter syntax. No redundancy, front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description covers input parameters but lacks output format or any example result. For a simple tool with no output schema, this is a gap in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and description restates parameter meanings almost verbatim, adding no new insight. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: infer coupling between tickets from code and suggest missing links. It explicitly distinguishes from siblings by noting suggestions are not folded into keystone/critical_path.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage context: suggestions only, never asserted or folded. It implies when to use for non-authoritative link suggestions, but lacks explicit comparison to all siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
For tickets with no code yet, predict which code areas each will likely touch and which tickets likely couple — by matching ticket text against a keyword index of the repo. Planning aid: suggestions only, never asserted, never used in keystone/critical_path. project_id accepts a name, slug, or UUID; repo_path is the absolute path to the project's local git checkout.
| Name | Required | Description | Default |
|---|---|---|---|
| repo_path | Yes | Absolute path to the project's local git checkout | |
| project_id | Yes | Linear project name, URL slug, or UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the tool is a suggestion only and not authoritative. However, it does not explicitly state it is read-only or describe side effects, though the context implies no destructive actions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no fluff. Purpose and mechanism in the first sentence, usage constraint in the second, and parameter details in the third. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, and description does not specify the return format beyond mentioning predictions of code areas and coupled tickets. It also omits potential error conditions. For a simple tool with minimal parameters, it covers essentials but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value by clarifying that project_id accepts name, slug, or UUID, and repo_path must be an absolute path. This aids the agent in correct parameter formatting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: predicting code areas and coupled tickets for tickets without code by matching text against a keyword index. It uses specific verbs and resources, and distinguishes from sibling tools like rank_keystones and critical_path.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use ('planning aid') and when not to use ('never used in keystone/critical_path'), providing clear context and implicitly contrasting with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report deterministic planning gaps in a project's dependency graph: cycles, isolated tickets, and high-leverage (keystone) tickets missing an estimate or owner. Analysis only — asserts nothing, writes nothing. project_id accepts a name, slug, or UUID.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Linear project name, URL slug, or UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description fully carries behavioral disclosure, clearly stating it is analysis-only and non-destructive. Details what gaps are reported. No mention of rate limits or data freshness, but transparency is adequate for a read-only analysis tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences delivering core purpose and key behavioral context. No fluff or redundancy. Front-loaded with the most critical information (what it reports, that it's read-only, parameter flexibility).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given single required parameter and no output schema, description adequately specifies input (project_id) and output content (cycles, isolated tickets, keystone gaps). Sufficient for an agent to select and invoke this tool correctly among siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter fully described. Description repeats the same info (name, slug, UUID) without adding new semantics beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports deterministic planning gaps: cycles, isolated tickets, and keystone tickets missing estimates or owners. It distinguishes from siblings like rank_keystones and critical_path by focusing on hygiene gaps and emphasizing analysis-only behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Analysis only — asserts nothing, writes nothing,' clarifying appropriate usage for read-only analysis. Provides parameter flexibility (name, slug, UUID). Lacks explicit when-not-to-use or alternative tool references for deeper context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct analytical purpose – from ranking keystones to computing critical paths, explaining blockers, suggesting code links/scope, surfacing gaps, grounding features, reconciling notes, listing projects, and rebuilding graphs – with no overlapping or ambiguous boundaries.
All tool names follow a consistent verb_noun pattern using snake_case (e.g., rank_keystones, list_projects, build_feature_graph), with no mixing of conventions or vague verbs.
With 10 tools, the set is well-scoped for a dependency analysis server – enough to cover essential analyses without redundancy or bloat.
The tool surface covers the full analytical lifecycle: project discovery, graph building, multi-angle dependency analysis, coupling inference, gap detection, feature grounding, and meeting note reconciliation – with no obvious gaps given the server's read-only, suggestion-only design.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server for Linear project management and issue tracking
The MCP server for Azure DevOps, bringing the power of Azure DevOps directly to your agents.
MCP server for generating rough-draft project plans from natural-language prompts.
MCP server for VC pitch-deck scoring, thesis-fit matching, and deal-flow management.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/0xdefence/PinchMCP'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
